diff --git a/CITATION.cff b/CITATION.cff index 0468883ea..e45b66336 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 877 pre-built adapters, with a focus on ERP and e-commerce + It ships 886 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 26152efa4..272543612 100644 --- a/README.de.md +++ b/README.de.md @@ -1,5 +1,5 @@

- AnythingMCP verbindet Claude, ChatGPT, Copilot und Gemini mit ERP-, E-Commerce-, REST-, SOAP- und SQL-Systemen und mit deinen Fileservern: 877 Connectors, dazu Firmengedächtnis, Skills und Dateisuche. + AnythingMCP verbindet Claude, ChatGPT, Copilot und Gemini mit ERP-, E-Commerce-, REST-, SOAP- und SQL-Systemen und mit deinen Fileservern: 886 Connectors, dazu Firmengedächtnis, Skills und Dateisuche.

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** | 877 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** | 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 | | **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 -877 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. +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. | Kategorie | Beispiele | |---|---| diff --git a/README.ja.md b/README.ja.md index 7d310b96c..564e70469 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,5 +1,5 @@

- AnythingMCP は Claude、ChatGPT、Copilot、Gemini を ERP、E コマース、REST、SOAP、SQL の各システムと社内のファイルサーバーにつなぎます。877 のコネクターに加え、社内メモリ、AI スキル、ファイル検索も備えています。 + AnythingMCP は Claude、ChatGPT、Copilot、Gemini を ERP、E コマース、REST、SOAP、SQL の各システムと社内のファイルサーバーにつなぎます。886 のコネクターに加え、社内メモリ、AI スキル、ファイル検索も備えています。

AnythingMCP:企業の頭脳になるオープンソースの MCP ゲートウェイ

@@ -20,7 +20,7 @@

AnythingMCP は、オープンソースのセルフホスト型 MCP ゲートウェイです。MCP サーバーを書かずに、Claude、ChatGPT、Copilot、Gemini を、自社で使っているソフトウェアやファイルサーバー上の文書につなぎます。
ゲートウェイの上には企業の頭脳を保持します。システム同士のつながりを表すナレッジグラフ、AI スキル、社内メモリです。すべての AI クライアントで共有され、ユーザーごとのロールで範囲が制限されます。
- SAP、Odoo、weclapp、Amazon Seller などを含む 877 種類の既製アダプターで 12,000 以上のツールを提供しており、うち 46 は API キー不要です。 + SAP、Odoo、weclapp、Amazon Seller などを含む 886 種類の既製アダプターで 12,000 以上のツールを提供しており、うち 46 は API キー不要です。

@@ -139,7 +139,7 @@ amd64 ではイメージの取得に約 30 秒、その 24 秒後に API が利 ## コネクターカタログ -877 個のアダプターで 12,000 以上のツールを提供しています。どのアダプターにも [anythingmcp.com/ja/guides](https://anythingmcp.com/ja/guides) に 7 言語の設定ガイドがあります。 +886 個のアダプターで 12,000 以上のツールを提供しています。どのアダプターにも [anythingmcp.com/ja/guides](https://anythingmcp.com/ja/guides) に 7 言語の設定ガイドがあります。 | カテゴリー | 例 | |---|---| diff --git a/README.md b/README.md index 29e19e087..b72925124 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- AnythingMCP connects Claude, ChatGPT, Copilot and Gemini to ERP, e-commerce, REST, SOAP and SQL systems and to your file servers: 877 connectors, plus company memory, skills and file search. + AnythingMCP connects Claude, ChatGPT, Copilot and Gemini to ERP, e-commerce, REST, SOAP and SQL systems and to your file servers: 886 connectors, plus company memory, skills and file search.

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.
- 877 ready connectors with 12,000+ tools, among them SAP, Odoo, weclapp and Amazon Seller; 46 need no API key. + 886 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 -877 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. +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. | Category | Examples | |---|---| diff --git a/README.zh-CN.md b/README.zh-CN.md index 5b51584fd..9b6edce39 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,5 +1,5 @@

- AnythingMCP 将 Claude、ChatGPT、Copilot 和 Gemini 连接到 ERP、电子商务、REST、SOAP 和 SQL 系统以及你的文件服务器:877 个连接器,还有企业记忆、技能和文件搜索。 + AnythingMCP 将 Claude、ChatGPT、Copilot 和 Gemini 连接到 ERP、电子商务、REST、SOAP 和 SQL 系统以及你的文件服务器:886 个连接器,还有企业记忆、技能和文件搜索。

AnythingMCP:成为你企业大脑的开源 MCP 网关

@@ -20,7 +20,7 @@

AnythingMCP 是一个开源、可自行托管的 MCP 网关,无需编写 MCP 服务器,即可将 Claude、ChatGPT、Copilot 和 Gemini 连接到你公司运行的软件以及文件服务器上的文档。
在网关之上,它还为你维护企业大脑:一张描述各系统如何关联的知识图谱、AI 技能和企业记忆,由所有 AI 客户端共享,并按每个用户的角色限制访问。
- 877 个现成连接器,提供 12,000 多个工具,涵盖 SAP、Odoo、weclapp 和 Amazon Seller 等;其中 46 个无需 API 密钥。 + 886 个现成连接器,提供 12,000 多个工具,涵盖 SAP、Odoo、weclapp 和 Amazon Seller 等;其中 46 个无需 API 密钥。

@@ -139,7 +139,7 @@ docker compose up -d ## 连接器目录 -共 877 个适配器,提供 12,000 多个工具。每个适配器都在 [anythingmcp.com/zh/guides](https://anythingmcp.com/zh/guides) 上提供七种语言的配置指南。 +共 886 个适配器,提供 12,000 多个工具。每个适配器都在 [anythingmcp.com/zh/guides](https://anythingmcp.com/zh/guides) 上提供七种语言的配置指南。 | 类别 | 示例 | |---|---| diff --git a/glama.json b/glama.json index 9a162f58c..0b495edc9 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: 877 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: 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." } diff --git a/llms-full.txt b/llms-full.txt index a29b27d6c..eb30de10a 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. 877 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. 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). --- @@ -93,7 +93,7 @@ Tools register at runtime, without a restart. Per-connector `{{VAR}}` values are ## Connector catalog -877 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. +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. | Category | Examples | |---|---| diff --git a/llms.txt b/llms.txt index 940b2653c..cc94fa26a 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. 877 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. 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). ## Getting started diff --git a/package.json b/package.json index 9ec7ecfe2..bc9b3b11b 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "anythingmcp", "version": "0.55.3", - "description": "Turn any REST/OpenAPI, SOAP/WSDL, GraphQL, OData or SQL API into MCP tools for Claude, ChatGPT and Copilot, no code. 877 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. 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).", "private": true, "license": "AGPL-3.0-only", "engines": { diff --git a/packages/backend/src/adapters/catalog.ts b/packages/backend/src/adapters/catalog.ts index c52d1faea..6132b1803 100644 --- a/packages/backend/src/adapters/catalog.ts +++ b/packages/backend/src/adapters/catalog.ts @@ -26,6 +26,7 @@ import * as easybill from './de/easybill.json'; import * as elo from './de/elo.json'; import * as fastbill from './de/fastbill.json'; import * as flour from './de/flour.json'; +import * as fressnapf from './de/fressnapf.json'; import * as getmyinvoices from './de/getmyinvoices.json'; import * as glsTracking from './de/gls-tracking.json'; import * as handelsregister from './de/handelsregister.json'; @@ -289,6 +290,7 @@ import * as firecrawl from './intl/firecrawl.json'; import * as fireflies from './intl/fireflies.json'; import * as firma from './intl/firma.json'; import * as fishAudio from './intl/fish-audio.json'; +import * as flowers1800 from './intl/flowers-1800.json'; import * as flutterwave from './intl/flutterwave.json'; import * as folk from './intl/folk.json'; import * as footballCharts from './intl/football-charts.json'; @@ -463,6 +465,7 @@ import * as microsoftTeams from './intl/microsoft-teams.json'; import * as microsoftTodo from './intl/microsoft-todo.json'; import * as microsoftWord from './intl/microsoft-word.json'; import * as mindbody from './intl/mindbody.json'; +import * as minted from './intl/minted.json'; import * as mintlify from './intl/mintlify.json'; import * as mirakl from './intl/mirakl.json'; import * as miraklConnect from './intl/mirakl-connect.json'; @@ -536,6 +539,7 @@ import * as paddle from './intl/paddle.json'; import * as pagerduty from './intl/pagerduty.json'; import * as pancake from './intl/pancake.json'; import * as pandadoc from './intl/pandadoc.json'; +import * as partsTown from './intl/parts-town.json'; import * as payhip from './intl/payhip.json'; import * as paypal from './intl/paypal.json'; import * as pazarama from './intl/pazarama.json'; @@ -816,6 +820,7 @@ import * as teamsystem from './it/teamsystem.json'; import * as zucchetti from './it/zucchetti.json'; import * as borme from './es/borme.json'; import * as bricoDepot from './es/brico-depot.json'; +import * as casaDelLibro from './es/casa-del-libro.json'; import * as elCorteIngles from './es/el-corte-ingles.json'; import * as holded from './es/holded.json'; import * as miravia from './es/miravia.json'; @@ -833,6 +838,7 @@ import * as dolibarr from './fr/dolibarr.json'; import * as eLeclerc from './fr/e-leclerc.json'; import * as fnac from './fr/fnac.json'; import * as frCompanyData from './fr/fr-company-data.json'; +import * as gacd from './fr/gacd.json'; import * as greenweez from './fr/greenweez.json'; import * as jardilandGammVert from './fr/jardiland-gamm-vert.json'; import * as kiabi from './fr/kiabi.json'; @@ -853,9 +859,11 @@ import * as sarenza from './fr/sarenza.json'; import * as sellsy from './fr/sellsy.json'; import * as ubaldi from './fr/ubaldi.json'; import * as afasProfit from './nl/afas-profit.json'; +import * as anwb from './nl/anwb.json'; import * as bolCom from './nl/bol-com.json'; import * as droppery from './nl/droppery.json'; import * as exactOnline from './nl/exact-online.json'; +import * as kruidvat from './nl/kruidvat.json'; import * as leenBakker from './nl/leen-bakker.json'; import * as marktplaats from './nl/marktplaats.json'; import * as moneybird from './nl/moneybird.json'; @@ -877,6 +885,7 @@ import * as stadium from './se/stadium.json'; import * as vismaEaccounting from './se/visma-eaccounting.json'; import * as eConomic from './dk/e-conomic.json'; import * as brreg from './no/brreg.json'; +import * as elkjop from './no/elkjop.json'; import * as prhYtj from './fi/prh-ytj.json'; import * as ares from './cz/ares.json'; import * as apaczka from './pl/apaczka.json'; @@ -1220,6 +1229,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ elo as unknown as AdapterDefinition, fastbill as unknown as AdapterDefinition, flour as unknown as AdapterDefinition, + fressnapf as unknown as AdapterDefinition, getmyinvoices as unknown as AdapterDefinition, glsTracking as unknown as AdapterDefinition, handelsregister as unknown as AdapterDefinition, @@ -1483,6 +1493,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ fireflies as unknown as AdapterDefinition, firma as unknown as AdapterDefinition, fishAudio as unknown as AdapterDefinition, + flowers1800 as unknown as AdapterDefinition, flutterwave as unknown as AdapterDefinition, folk as unknown as AdapterDefinition, footballCharts as unknown as AdapterDefinition, @@ -1657,6 +1668,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ microsoftTodo as unknown as AdapterDefinition, microsoftWord as unknown as AdapterDefinition, mindbody as unknown as AdapterDefinition, + minted as unknown as AdapterDefinition, mintlify as unknown as AdapterDefinition, mirakl as unknown as AdapterDefinition, miraklConnect as unknown as AdapterDefinition, @@ -1730,6 +1742,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ pagerduty as unknown as AdapterDefinition, pancake as unknown as AdapterDefinition, pandadoc as unknown as AdapterDefinition, + partsTown as unknown as AdapterDefinition, payhip as unknown as AdapterDefinition, paypal as unknown as AdapterDefinition, pazarama as unknown as AdapterDefinition, @@ -2010,6 +2023,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ zucchetti as unknown as AdapterDefinition, borme as unknown as AdapterDefinition, bricoDepot as unknown as AdapterDefinition, + casaDelLibro as unknown as AdapterDefinition, elCorteIngles as unknown as AdapterDefinition, holded as unknown as AdapterDefinition, miravia as unknown as AdapterDefinition, @@ -2027,6 +2041,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ eLeclerc as unknown as AdapterDefinition, fnac as unknown as AdapterDefinition, frCompanyData as unknown as AdapterDefinition, + gacd as unknown as AdapterDefinition, greenweez as unknown as AdapterDefinition, jardilandGammVert as unknown as AdapterDefinition, kiabi as unknown as AdapterDefinition, @@ -2047,9 +2062,11 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ sellsy as unknown as AdapterDefinition, ubaldi as unknown as AdapterDefinition, afasProfit as unknown as AdapterDefinition, + anwb as unknown as AdapterDefinition, bolCom as unknown as AdapterDefinition, droppery as unknown as AdapterDefinition, exactOnline as unknown as AdapterDefinition, + kruidvat as unknown as AdapterDefinition, leenBakker as unknown as AdapterDefinition, marktplaats as unknown as AdapterDefinition, moneybird as unknown as AdapterDefinition, @@ -2071,6 +2088,7 @@ const RAW_ADAPTERS: AdapterDefinition[] = [ vismaEaccounting as unknown as AdapterDefinition, eConomic as unknown as AdapterDefinition, brreg as unknown as AdapterDefinition, + elkjop as unknown as AdapterDefinition, prhYtj as unknown as AdapterDefinition, ares as unknown as AdapterDefinition, apaczka as unknown as AdapterDefinition, diff --git a/packages/backend/src/adapters/de/fressnapf.json b/packages/backend/src/adapters/de/fressnapf.json new file mode 100644 index 000000000..80bd69ef4 --- /dev/null +++ b/packages/backend/src/adapters/de/fressnapf.json @@ -0,0 +1,2033 @@ +{ + "slug": "fressnapf", + "name": "Fressnapf Marketplace", + "aliases": [ + "Fressnapf Marktplatz", + "Fressnapf seller API", + "Fressnapf Partner", + "fressnapf.de", + "fressnapf.at", + "Fressnapf Mirakl" + ], + "description": "Run your shop on the Fressnapf 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 and Austria; sign in with the shop API key from your Fressnapf seller back office.", + "instructions": "## Fressnapf Marketplace\nRun your shop on the Fressnapf marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Fressnapf, returns, order documents, invoices and transactions. The connector calls the Fressnapf seller platform at `https://fressnapfde-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 and Austria. The marketplace opened on fressnapf.de in 2022 and on fressnapf.at in 2024.\n\n**Who can sell**: Fressnapf selects its partners through the contact form on its marketplace page, which asks for the addresses of your other marketplace shops, the number of articles and whether an integrator connects you. Partners ship their own orders and take back their own returns. The connector needs a seller account that Fressnapf 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 Fressnapf seller back office: `https://fressnapfde-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 `FRESSNAPF_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. A seller in both Germany and Austria may have one shop per country under the same user; the shop id picks the shop. If your user has more than one shop, set `FRESSNAPF_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 `fressnapf_get_account`); to work on several shops, install the connector once per shop. Without it your default shop is used.\n4. Install and run `fressnapf_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Fressnapf 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**: `fressnapf_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `fressnapf_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `fressnapf_list_offers` for prices and stock and `fressnapf_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `fressnapf_get_products` looks products up in the Fressnapf catalog by EAN or another reference and returns the marketplace product SKU; `fressnapf_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`. `fressnapf_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `fressnapf_update_tracking` stores the carrier and tracking number (carrier codes come from `fressnapf_list_carriers`) and `fressnapf_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `fressnapf_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `fressnapf_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 `fressnapf_list_order_documents`.\n\n**Writes: confirm first.** `fressnapf_accept_order`, `fressnapf_update_tracking`, `fressnapf_ship_order`, `fressnapf_resolve_incident`, `fressnapf_accept_return`, `fressnapf_receive_return`, `fressnapf_update_offers`, `fressnapf_reply_thread`, `fressnapf_create_order_thread` and `fressnapf_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. `fressnapf_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)**: `fressnapf_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 (`fressnapf_get_offer` or `fressnapf_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 `fressnapf_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `fressnapf_list_offer_conditions`, logistic class codes from `fressnapf_list_logistic_classes`.\n\n**File imports**: `fressnapf_import_products` (P41) and `fressnapf_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Fressnapf asks for; the connector downloads it and uploads it to Fressnapf. Track them with `fressnapf_list_product_imports` / `fressnapf_get_product_import` and `fressnapf_list_offer_imports` / `fressnapf_get_offer_import`.\n\n**Returns**: `fressnapf_list_returns` (RT11) lists return requests. Where Fressnapf lets the shop decide, `fressnapf_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `fressnapf_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `fressnapf_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `fressnapf_get_thread` reads one with its messages, `fressnapf_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Fressnapf) and `fressnapf_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `fressnapf_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `fressnapf_list_invoices` (IV01) lists the accounting documents Fressnapf issues to the shop and `fressnapf_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Fressnapf uses Enhanced Seller Invoicing, IV01 returns no new documents; use `fressnapf_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 `fressnapf_export_offers`, poll `fressnapf_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `fressnapf_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 `fressnapf_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 `fressnapf_get_account` and the same `shop_id`. Without `shop_id` a call uses `FRESSNAPF_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**: `fressnapf_list_channels` (country sites), `fressnapf_list_carriers`, `fressnapf_list_shipping_zones`, `fressnapf_list_shipping_methods` and `fressnapf_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 Fressnapf can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `fressnapf_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": "fressnapf", + "docsUrl": "https://www.fressnapf.de/marktplatz/", + "requiredEnvVars": [ + "FRESSNAPF_API_KEY" + ], + "optionalEnvVars": [ + "FRESSNAPF_SHOP_ID" + ], + "prerequisites": "An open seller account with Fressnapf and access to its seller back office to generate the shop API key. Fressnapf selects its partners through the contact form on its marketplace page, which asks for the addresses of your other marketplace shops, the number of articles and whether an integrator connects you. Partners ship their own orders and take back their own returns.", + "envVarMeta": { + "FRESSNAPF_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Fressnapf 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://fressnapfde-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "FRESSNAPF_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "A seller in both Germany and Austria may have one shop per country under the same user; the shop id picks the shop. With more than one shop, enter the numeric id of the shop to use (on the back office dashboard, next to Identifier or Shop ID). Leave empty to use your default shop.", + "example": "2001", + "pattern": "^[0-9]+$", + "patternMessage": "The shop id is a number." + } + }, + "verifyHints": { + "401": "Fressnapf refused the API key. Check that FRESSNAPF_API_KEY is the shop key from your Fressnapf 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 FRESSNAPF_SHOP_ID to a shop you manage.", + "404": "The Fressnapf seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://fressnapfde-prod.mirakl.net: Fressnapf may have moved its seller back office.", + "rate_limited": "Fressnapf is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "fressnapf_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 Fressnapf 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 Fressnapf seller account", + "body": "Sign in to the Fressnapf seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Fressnapf seller back office", + "url": "https://fressnapfde-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 Fressnapf (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": "Fressnapf selects its partners through the contact form on its marketplace page, which asks for the addresses of your other marketplace shops, the number of articles and whether an integrator connects you. Partners ship their own orders and take back their own returns. See [the Fressnapf seller page](https://www.fressnapf.de/marktplatz/)." + } + ] + }, + { + "id": "api-key", + "title": "Paste the key", + "body": "Paste the key alone, without `Bearer`, quotes or spaces. A seller in both Germany and Austria may have one shop per country under the same user; the shop id picks the shop. If your user has more than one shop, also enter the id of the shop to use.", + "fields": [ + "FRESSNAPF_API_KEY", + "FRESSNAPF_SHOP_ID" + ], + "problems": [ + { + "q": "Fressnapf 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": "Fressnapf Marketplace", + "type": "REST", + "baseUrl": "https://fressnapfde-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{FRESSNAPF_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by fressnapf_update_offers or fressnapf_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 fressnapf_update_offers or fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_get_offer_export_status about once a minute until COMPLETED, then read each file with fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_get_offer_export_status", + "description": "Status of an offer export started with fressnapf_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 fressnapf_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 Fressnapf 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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_list_threads", + "description": "List message threads (M11) with customers and Fressnapf: 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 Fressnapf)." + }, + "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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_list_invoices", + "description": "List the accounting documents Fressnapf 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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_list_document_requests", + "description": "List accounting document requests (DR11), used when Fressnapf runs Enhanced Seller Invoicing: invoices and credit notes that Fressnapf 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 Fressnapf (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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_list_orders and fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "fressnapf_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from fressnapf_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 fressnapf_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in fressnapf_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_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": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "fressnapf_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 fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "fressnapf_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Fressnapf. 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 fressnapf_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 (Fressnapf) 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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_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": "fressnapf_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Fressnapf 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 (Fressnapf) 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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_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": "fressnapf_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 fressnapf_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 fressnapf_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "fressnapf_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Fressnapf 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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_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": "FRESSNAPF_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": "fressnapf_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 fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "FRESSNAPF_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "fressnapf_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 Fressnapf asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with fressnapf_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 Fressnapf 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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "FRESSNAPF_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": "fressnapf_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 Fressnapf asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with fressnapf_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 fressnapf_get_account, also shown in the back office). Leave it out to use FRESSNAPF_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "FRESSNAPF_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/fressnapf.live.spec.ts b/packages/backend/src/adapters/de/fressnapf.live.spec.ts new file mode 100644 index 000000000..b0512ac06 --- /dev/null +++ b/packages/backend/src/adapters/de/fressnapf.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './fressnapf.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_FRESSNAPF_LIVE=1 (GET /api/version needs no key; the shop reads need FRESSNAPF_API_KEY). +describeRetailerAdapter(adapter, { slug: 'fressnapf', hosts: ['fressnapfde-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/es/casa-del-libro.json b/packages/backend/src/adapters/es/casa-del-libro.json new file mode 100644 index 000000000..2ccf9969a --- /dev/null +++ b/packages/backend/src/adapters/es/casa-del-libro.json @@ -0,0 +1,2033 @@ +{ + "slug": "casa-del-libro", + "name": "Casa del Libro Marketplace", + "aliases": [ + "Casa del Libro seller API", + "Casa del Libro vendedores", + "casadellibro.com marketplace", + "Casa del Libro Mirakl", + "Grupo Planeta", + "CDL marketplace" + ], + "description": "Run your shop on the Casa del Libro 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 Casa del Libro seller back office.", + "instructions": "## Casa del Libro Marketplace\nRun your shop on the Casa del Libro marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Casa del Libro, returns, order documents, invoices and transactions. The connector calls the Casa del Libro seller platform at `https://marketplace.casadellibro.com` 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**: Casa del Libro reviews each seller application. It has two seller plans: a professional plan with a monthly fee, charged only in months with sales, and an individual plan with a fixed fee per item sold; both pay a 15% commission. Offers attach to products already in the Casa del Libro catalogue, and only the professional plan can create missing products. Sellers ship each order themselves within a 3 to 5 day delivery window. The connector needs a seller account that Casa del Libro has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Casa del Libro seller back office: `https://marketplace.casadellibro.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 `CASA_DEL_LIBRO_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 `CASA_DEL_LIBRO_SHOP_ID` empty. Only if your user manages several shops on Casa del Libro, set `CASA_DEL_LIBRO_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 `casa_del_libro_get_account`). Without it your default shop is used.\n4. Install and run `casa_del_libro_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Casa del Libro 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**: `casa_del_libro_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `casa_del_libro_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `casa_del_libro_list_offers` for prices and stock and `casa_del_libro_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `casa_del_libro_get_products` looks products up in the Casa del Libro catalog by EAN or another reference and returns the marketplace product SKU; `casa_del_libro_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`. `casa_del_libro_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `casa_del_libro_update_tracking` stores the carrier and tracking number (carrier codes come from `casa_del_libro_list_carriers`) and `casa_del_libro_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `casa_del_libro_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `casa_del_libro_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 `casa_del_libro_list_order_documents`.\n\n**Writes: confirm first.** `casa_del_libro_accept_order`, `casa_del_libro_update_tracking`, `casa_del_libro_ship_order`, `casa_del_libro_resolve_incident`, `casa_del_libro_accept_return`, `casa_del_libro_receive_return`, `casa_del_libro_update_offers`, `casa_del_libro_reply_thread`, `casa_del_libro_create_order_thread` and `casa_del_libro_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. `casa_del_libro_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)**: `casa_del_libro_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 (`casa_del_libro_get_offer` or `casa_del_libro_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 `casa_del_libro_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `casa_del_libro_list_offer_conditions`, logistic class codes from `casa_del_libro_list_logistic_classes`.\n\n**File imports**: `casa_del_libro_import_products` (P41) and `casa_del_libro_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Casa del Libro asks for; the connector downloads it and uploads it to Casa del Libro. Track them with `casa_del_libro_list_product_imports` / `casa_del_libro_get_product_import` and `casa_del_libro_list_offer_imports` / `casa_del_libro_get_offer_import`.\n\n**Returns**: `casa_del_libro_list_returns` (RT11) lists return requests. Where Casa del Libro lets the shop decide, `casa_del_libro_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `casa_del_libro_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `casa_del_libro_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `casa_del_libro_get_thread` reads one with its messages, `casa_del_libro_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Casa del Libro) and `casa_del_libro_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `casa_del_libro_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `casa_del_libro_list_invoices` (IV01) lists the accounting documents Casa del Libro issues to the shop and `casa_del_libro_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Casa del Libro uses Enhanced Seller Invoicing, IV01 returns no new documents; use `casa_del_libro_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 `casa_del_libro_export_offers`, poll `casa_del_libro_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `casa_del_libro_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 `casa_del_libro_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 `casa_del_libro_get_account` and the same `shop_id`. Without `shop_id` a call uses `CASA_DEL_LIBRO_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**: `casa_del_libro_list_channels` (country sites), `casa_del_libro_list_carriers`, `casa_del_libro_list_shipping_zones`, `casa_del_libro_list_shipping_methods` and `casa_del_libro_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 Casa del Libro can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `casa_del_libro_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": "casa-del-libro", + "docsUrl": "https://marketplace.casadellibro.com/login", + "requiredEnvVars": [ + "CASA_DEL_LIBRO_API_KEY" + ], + "optionalEnvVars": [ + "CASA_DEL_LIBRO_SHOP_ID" + ], + "prerequisites": "An open seller account with Casa del Libro and access to its seller back office to generate the shop API key. Casa del Libro reviews each seller application. It has two seller plans: a professional plan with a monthly fee, charged only in months with sales, and an individual plan with a fixed fee per item sold; both pay a 15% commission. Offers attach to products already in the Casa del Libro catalogue, and only the professional plan can create missing products. Sellers ship each order themselves within a 3 to 5 day delivery window.", + "envVarMeta": { + "CASA_DEL_LIBRO_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Casa del Libro 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.casadellibro.com/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "CASA_DEL_LIBRO_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on Casa del Libro: 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": "Casa del Libro refused the API key. Check that CASA_DEL_LIBRO_API_KEY is the shop key from your Casa del Libro 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 CASA_DEL_LIBRO_SHOP_ID to a shop you manage.", + "404": "The Casa del Libro 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.casadellibro.com: Casa del Libro may have moved its seller back office.", + "rate_limited": "Casa del Libro is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "casa_del_libro_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 Casa del Libro 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 Casa del Libro seller account", + "body": "Sign in to the Casa del Libro seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Casa del Libro seller back office", + "url": "https://marketplace.casadellibro.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 Casa del Libro (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": "Casa del Libro reviews each seller application. It has two seller plans: a professional plan with a monthly fee, charged only in months with sales, and an individual plan with a fixed fee per item sold; both pay a 15% commission. Offers attach to products already in the Casa del Libro catalogue, and only the professional plan can create missing products. Sellers ship each order themselves within a 3 to 5 day delivery window." + } + ] + }, + { + "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": [ + "CASA_DEL_LIBRO_API_KEY", + "CASA_DEL_LIBRO_SHOP_ID" + ], + "problems": [ + { + "q": "Casa del Libro 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": "Casa del Libro Marketplace", + "type": "REST", + "baseUrl": "https://marketplace.casadellibro.com/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{CASA_DEL_LIBRO_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by casa_del_libro_update_offers or casa_del_libro_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 casa_del_libro_update_offers or casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_offer_export_status about once a minute until COMPLETED, then read each file with casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_get_offer_export_status", + "description": "Status of an offer export started with casa_del_libro_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 casa_del_libro_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 Casa del Libro 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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_list_threads", + "description": "List message threads (M11) with customers and Casa del Libro: 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 Casa del Libro)." + }, + "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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_list_invoices", + "description": "List the accounting documents Casa del Libro 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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_list_document_requests", + "description": "List accounting document requests (DR11), used when Casa del Libro runs Enhanced Seller Invoicing: invoices and credit notes that Casa del Libro 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 Casa del Libro (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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_list_orders and casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "casa_del_libro_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from casa_del_libro_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 casa_del_libro_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in casa_del_libro_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "casa_del_libro_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Casa del Libro. 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 casa_del_libro_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 (Casa del Libro) 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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_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": "casa_del_libro_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Casa del Libro 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 (Casa del Libro) 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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "casa_del_libro_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Casa del Libro 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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_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": "CASA_DEL_LIBRO_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": "casa_del_libro_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 casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "casa_del_libro_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 Casa del Libro asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with casa_del_libro_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 Casa del Libro 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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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": "casa_del_libro_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 Casa del Libro asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with casa_del_libro_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 casa_del_libro_get_account, also shown in the back office). Leave it out to use CASA_DEL_LIBRO_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "CASA_DEL_LIBRO_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/casa-del-libro.live.spec.ts b/packages/backend/src/adapters/es/casa-del-libro.live.spec.ts new file mode 100644 index 000000000..6af4d18c4 --- /dev/null +++ b/packages/backend/src/adapters/es/casa-del-libro.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './casa-del-libro.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_CASA_DEL_LIBRO_LIVE=1 (GET /api/version needs no key; the shop reads need CASA_DEL_LIBRO_API_KEY). +describeRetailerAdapter(adapter, { slug: 'casa-del-libro', hosts: ['marketplace.casadellibro.com'] }); diff --git a/packages/backend/src/adapters/fr/gacd.json b/packages/backend/src/adapters/fr/gacd.json new file mode 100644 index 000000000..a6977aef0 --- /dev/null +++ b/packages/backend/src/adapters/fr/gacd.json @@ -0,0 +1,2033 @@ +{ + "slug": "gacd", + "name": "GACD Marketplace", + "aliases": [ + "GACD seller API", + "GACD marketplace dentaire", + "The Dental Marketplace", + "TDMP", + "GACD Mirakl", + "tdmp.mirakl.net" + ], + "description": "Run your shop on the GACD 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 GACD seller back office.", + "instructions": "## GACD Marketplace\nRun your shop on the GACD marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and GACD, returns, order documents, invoices and transactions. The connector calls the GACD seller platform at `https://tdmp.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**: GACD opens seller accounts on request: contact its sales team. The marketplace sells to dental practices in France, from dental supplies and equipment to furniture and office products, and GACD only accepts products with an EAN. The connector needs a seller account that GACD has already opened.\n\n**Setup (about 5 minutes)**\n1. Sign in to the GACD seller back office: `https://tdmp.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 `GACD_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 `GACD_SHOP_ID` empty. Only if your user manages several shops on GACD, set `GACD_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 `gacd_get_account`). Without it your default shop is used.\n4. Install and run `gacd_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the GACD 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**: `gacd_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `gacd_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `gacd_list_offers` for prices and stock and `gacd_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `gacd_get_products` looks products up in the GACD catalog by EAN or another reference and returns the marketplace product SKU; `gacd_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`. `gacd_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `gacd_update_tracking` stores the carrier and tracking number (carrier codes come from `gacd_list_carriers`) and `gacd_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `gacd_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `gacd_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 `gacd_list_order_documents`.\n\n**Writes: confirm first.** `gacd_accept_order`, `gacd_update_tracking`, `gacd_ship_order`, `gacd_resolve_incident`, `gacd_accept_return`, `gacd_receive_return`, `gacd_update_offers`, `gacd_reply_thread`, `gacd_create_order_thread` and `gacd_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. `gacd_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)**: `gacd_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 (`gacd_get_offer` or `gacd_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 `gacd_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `gacd_list_offer_conditions`, logistic class codes from `gacd_list_logistic_classes`.\n\n**File imports**: `gacd_import_products` (P41) and `gacd_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format GACD asks for; the connector downloads it and uploads it to GACD. Track them with `gacd_list_product_imports` / `gacd_get_product_import` and `gacd_list_offer_imports` / `gacd_get_offer_import`.\n\n**Returns**: `gacd_list_returns` (RT11) lists return requests. Where GACD lets the shop decide, `gacd_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `gacd_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `gacd_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `gacd_get_thread` reads one with its messages, `gacd_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is GACD) and `gacd_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `gacd_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `gacd_list_invoices` (IV01) lists the accounting documents GACD issues to the shop and `gacd_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If GACD uses Enhanced Seller Invoicing, IV01 returns no new documents; use `gacd_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 `gacd_export_offers`, poll `gacd_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `gacd_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 `gacd_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 `gacd_get_account` and the same `shop_id`. Without `shop_id` a call uses `GACD_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**: `gacd_list_channels` (country sites), `gacd_list_carriers`, `gacd_list_shipping_zones`, `gacd_list_shipping_methods` and `gacd_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 GACD can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `gacd_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": "gacd", + "docsUrl": "https://tdmp.mirakl.net/login", + "requiredEnvVars": [ + "GACD_API_KEY" + ], + "optionalEnvVars": [ + "GACD_SHOP_ID" + ], + "prerequisites": "An open seller account with GACD and access to its seller back office to generate the shop API key. GACD opens seller accounts on request: contact its sales team. The marketplace sells to dental practices in France, from dental supplies and equipment to furniture and office products, and GACD only accepts products with an EAN.", + "envVarMeta": { + "GACD_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "GACD 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://tdmp.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "GACD_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on GACD: 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": "GACD refused the API key. Check that GACD_API_KEY is the shop key from your GACD 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 GACD_SHOP_ID to a shop you manage.", + "404": "The GACD seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://tdmp.mirakl.net: GACD may have moved its seller back office.", + "rate_limited": "GACD is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "gacd_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 GACD 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 GACD seller account", + "body": "Sign in to the GACD seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the GACD seller back office", + "url": "https://tdmp.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 GACD (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": "GACD opens seller accounts on request: contact its sales team. The marketplace sells to dental practices in France, from dental supplies and equipment to furniture and office products, and GACD only accepts products with an EAN." + } + ] + }, + { + "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": [ + "GACD_API_KEY", + "GACD_SHOP_ID" + ], + "problems": [ + { + "q": "GACD 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": "GACD Marketplace", + "type": "REST", + "baseUrl": "https://tdmp.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{GACD_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "GACD_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": "gacd_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by gacd_update_offers or gacd_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 gacd_update_offers or gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_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 gacd_get_offer_export_status about once a minute until COMPLETED, then read each file with gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "GACD_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": "gacd_get_offer_export_status", + "description": "Status of an offer export started with gacd_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 gacd_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 GACD 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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "GACD_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": "gacd_list_threads", + "description": "List message threads (M11) with customers and GACD: 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 GACD)." + }, + "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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_list_invoices", + "description": "List the accounting documents GACD 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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "GACD_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": "gacd_list_document_requests", + "description": "List accounting document requests (DR11), used when GACD runs Enhanced Seller Invoicing: invoices and credit notes that GACD 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 GACD (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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_list_orders and gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "gacd_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from gacd_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 gacd_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in gacd_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_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": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "gacd_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 gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "gacd_reply_thread", + "description": "Reply in a message thread (M12) to the customer or GACD. 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 gacd_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 (GACD) 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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_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": "gacd_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, GACD 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 (GACD) 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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_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": "gacd_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 gacd_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 gacd_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "gacd_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when GACD 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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_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": "GACD_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": "gacd_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 gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "GACD_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "gacd_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 GACD asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with gacd_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 GACD 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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "GACD_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": "gacd_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 GACD asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with gacd_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 gacd_get_account, also shown in the back office). Leave it out to use GACD_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "GACD_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/gacd.live.spec.ts b/packages/backend/src/adapters/fr/gacd.live.spec.ts new file mode 100644 index 000000000..2f11c34ee --- /dev/null +++ b/packages/backend/src/adapters/fr/gacd.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './gacd.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_GACD_LIVE=1 (GET /api/version needs no key; the shop reads need GACD_API_KEY). +describeRetailerAdapter(adapter, { slug: 'gacd', hosts: ['tdmp.mirakl.net'] }); diff --git a/packages/backend/src/adapters/intl/flowers-1800.json b/packages/backend/src/adapters/intl/flowers-1800.json new file mode 100644 index 000000000..deb153974 --- /dev/null +++ b/packages/backend/src/adapters/intl/flowers-1800.json @@ -0,0 +1,2033 @@ +{ + "slug": "flowers-1800", + "name": "1-800-Flowers.com Marketplace", + "aliases": [ + "1800 Flowers", + "1800flowers", + "1-800-Flowers", + "1-800-Flowers seller API", + "1800Flowers Marketplace", + "1-800-Flowers Mirakl" + ], + "description": "Run your shop on the 1-800-Flowers.com 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 1-800-Flowers.com seller back office.", + "instructions": "## 1-800-Flowers.com Marketplace\nRun your shop on the 1-800-Flowers.com marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and 1-800-Flowers.com, returns, order documents, invoices and transactions. The connector calls the 1-800-Flowers.com seller platform at `https://1800flowers-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**: 1-800-Flowers.com approves each product for its marketplace assortment; apply with the Start Selling form on its sellers page. The commission is 25 % of the selling price plus shipping, and baby, children's and food products need extra insurance and compliance documents. The connector needs a seller account that 1-800-Flowers.com 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 1-800-Flowers.com seller back office: `https://1800flowers-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 `FLOWERS_1800_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 `FLOWERS_1800_SHOP_ID` empty. Only if your user manages several shops on 1-800-Flowers.com, set `FLOWERS_1800_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 `flowers_1800_get_account`). Without it your default shop is used.\n4. Install and run `flowers_1800_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the 1-800-Flowers.com 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**: `flowers_1800_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `flowers_1800_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `flowers_1800_list_offers` for prices and stock and `flowers_1800_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `flowers_1800_get_products` looks products up in the 1-800-Flowers.com catalog by EAN or another reference and returns the marketplace product SKU; `flowers_1800_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`. `flowers_1800_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `flowers_1800_update_tracking` stores the carrier and tracking number (carrier codes come from `flowers_1800_list_carriers`) and `flowers_1800_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `flowers_1800_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `flowers_1800_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 `flowers_1800_list_order_documents`.\n\n**Writes: confirm first.** `flowers_1800_accept_order`, `flowers_1800_update_tracking`, `flowers_1800_ship_order`, `flowers_1800_resolve_incident`, `flowers_1800_accept_return`, `flowers_1800_receive_return`, `flowers_1800_update_offers`, `flowers_1800_reply_thread`, `flowers_1800_create_order_thread` and `flowers_1800_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. `flowers_1800_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)**: `flowers_1800_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 (`flowers_1800_get_offer` or `flowers_1800_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 `flowers_1800_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `flowers_1800_list_offer_conditions`, logistic class codes from `flowers_1800_list_logistic_classes`.\n\n**File imports**: `flowers_1800_import_products` (P41) and `flowers_1800_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format 1-800-Flowers.com asks for; the connector downloads it and uploads it to 1-800-Flowers.com. Track them with `flowers_1800_list_product_imports` / `flowers_1800_get_product_import` and `flowers_1800_list_offer_imports` / `flowers_1800_get_offer_import`.\n\n**Returns**: `flowers_1800_list_returns` (RT11) lists return requests. Where 1-800-Flowers.com lets the shop decide, `flowers_1800_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `flowers_1800_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `flowers_1800_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `flowers_1800_get_thread` reads one with its messages, `flowers_1800_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is 1-800-Flowers.com) and `flowers_1800_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `flowers_1800_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `flowers_1800_list_invoices` (IV01) lists the accounting documents 1-800-Flowers.com issues to the shop and `flowers_1800_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If 1-800-Flowers.com uses Enhanced Seller Invoicing, IV01 returns no new documents; use `flowers_1800_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 `flowers_1800_export_offers`, poll `flowers_1800_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `flowers_1800_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 `flowers_1800_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 `flowers_1800_get_account` and the same `shop_id`. Without `shop_id` a call uses `FLOWERS_1800_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**: `flowers_1800_list_channels` (country sites), `flowers_1800_list_carriers`, `flowers_1800_list_shipping_zones`, `flowers_1800_list_shipping_methods` and `flowers_1800_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 1-800-Flowers.com can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `flowers_1800_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": "flowers-1800", + "docsUrl": "https://www.1800flowers.com/sellers", + "requiredEnvVars": [ + "FLOWERS_1800_API_KEY" + ], + "optionalEnvVars": [ + "FLOWERS_1800_SHOP_ID" + ], + "prerequisites": "An open seller account with 1-800-Flowers.com and access to its seller back office to generate the shop API key. 1-800-Flowers.com approves each product for its marketplace assortment; apply with the Start Selling form on its sellers page. The commission is 25 % of the selling price plus shipping, and baby, children's and food products need extra insurance and compliance documents.", + "envVarMeta": { + "FLOWERS_1800_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "1-800-Flowers.com 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://1800flowers-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "FLOWERS_1800_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on 1-800-Flowers.com: 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": "1-800-Flowers.com refused the API key. Check that FLOWERS_1800_API_KEY is the shop key from your 1-800-Flowers.com 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 FLOWERS_1800_SHOP_ID to a shop you manage.", + "404": "The 1-800-Flowers.com seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://1800flowers-prod.mirakl.net: 1-800-Flowers.com may have moved its seller back office.", + "rate_limited": "1-800-Flowers.com is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "flowers_1800_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 1-800-Flowers.com 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 1-800-Flowers.com seller account", + "body": "Sign in to the 1-800-Flowers.com seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the 1-800-Flowers.com seller back office", + "url": "https://1800flowers-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 1-800-Flowers.com (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": "1-800-Flowers.com approves each product for its marketplace assortment; apply with the Start Selling form on its sellers page. The commission is 25 % of the selling price plus shipping, and baby, children's and food products need extra insurance and compliance documents. See [the 1-800-Flowers.com seller page](https://www.1800flowers.com/sellers)." + } + ] + }, + { + "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": [ + "FLOWERS_1800_API_KEY", + "FLOWERS_1800_SHOP_ID" + ], + "problems": [ + { + "q": "1-800-Flowers.com 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": "1-800-Flowers.com Marketplace", + "type": "REST", + "baseUrl": "https://1800flowers-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{FLOWERS_1800_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by flowers_1800_update_offers or flowers_1800_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 flowers_1800_update_offers or flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_get_offer_export_status about once a minute until COMPLETED, then read each file with flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_get_offer_export_status", + "description": "Status of an offer export started with flowers_1800_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 flowers_1800_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 1-800-Flowers.com 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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_list_threads", + "description": "List message threads (M11) with customers and 1-800-Flowers.com: 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 1-800-Flowers.com)." + }, + "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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_list_invoices", + "description": "List the accounting documents 1-800-Flowers.com 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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_list_document_requests", + "description": "List accounting document requests (DR11), used when 1-800-Flowers.com runs Enhanced Seller Invoicing: invoices and credit notes that 1-800-Flowers.com 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 1-800-Flowers.com (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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_list_orders and flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "flowers_1800_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from flowers_1800_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 flowers_1800_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in flowers_1800_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "flowers_1800_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 flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "flowers_1800_reply_thread", + "description": "Reply in a message thread (M12) to the customer or 1-800-Flowers.com. 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 flowers_1800_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 (1-800-Flowers.com) 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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_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": "flowers_1800_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, 1-800-Flowers.com 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 (1-800-Flowers.com) 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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_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 flowers_1800_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "flowers_1800_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when 1-800-Flowers.com 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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_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": "FLOWERS_1800_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": "flowers_1800_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 flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "FLOWERS_1800_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "flowers_1800_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 1-800-Flowers.com asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with flowers_1800_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 1-800-Flowers.com 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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "FLOWERS_1800_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": "flowers_1800_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 1-800-Flowers.com asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with flowers_1800_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 flowers_1800_get_account, also shown in the back office). Leave it out to use FLOWERS_1800_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "FLOWERS_1800_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/flowers-1800.live.spec.ts b/packages/backend/src/adapters/intl/flowers-1800.live.spec.ts new file mode 100644 index 000000000..7ebdb6713 --- /dev/null +++ b/packages/backend/src/adapters/intl/flowers-1800.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './flowers-1800.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_FLOWERS_1800_LIVE=1 (GET /api/version needs no key; the shop reads need FLOWERS_1800_API_KEY). +describeRetailerAdapter(adapter, { slug: 'flowers-1800', hosts: ['1800flowers-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/intl/leroy-merlin.json b/packages/backend/src/adapters/intl/leroy-merlin.json index 5b25b5fd0..de1345722 100644 --- a/packages/backend/src/adapters/intl/leroy-merlin.json +++ b/packages/backend/src/adapters/intl/leroy-merlin.json @@ -5,7 +5,8 @@ "Leroy Merlin seller API", "Leroy Merlin Mirakl", "ADEO Marketplace", - "Bricoman" + "Bricoman", + "Tecnomat" ], "description": "Run your shop on the Leroy Merlin 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, Italy, Spain and Portugal; sign in with the shop API key from your Leroy Merlin seller back office.", "instructions": "## Leroy Merlin Marketplace\nRun your shop on the Leroy Merlin marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Leroy Merlin, returns, order documents, invoices and transactions. The connector calls the Leroy Merlin seller platform at `https://adeo-marketplace.mirakl.net` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: France, Italy, Spain and Portugal. Bricoman France sells from the same shop.\n\n**Who can sell**: Leroy Merlin takes applications through a form, followed by a business verification (KYC). The connector needs a seller account that Leroy Merlin has already opened.\n\nLeroy Merlin Poland (a separate shop in PLN) and Romania run on other addresses, which this connector does not reach.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Leroy Merlin seller back office: `https://adeo-marketplace.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 `LEROY_MERLIN_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. Users with several shops are common on Leroy Merlin. If your user has more than one shop, set `LEROY_MERLIN_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 `leroy_merlin_get_account`); to work on several shops, install the connector once per shop. Without it your default shop is used.\n4. Install and run `leroy_merlin_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Leroy Merlin 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**: `leroy_merlin_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `leroy_merlin_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `leroy_merlin_list_offers` for prices and stock and `leroy_merlin_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `leroy_merlin_get_products` looks products up in the Leroy Merlin catalog by EAN or another reference and returns the marketplace product SKU; `leroy_merlin_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`. `leroy_merlin_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `leroy_merlin_update_tracking` stores the carrier and tracking number (carrier codes come from `leroy_merlin_list_carriers`) and `leroy_merlin_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `leroy_merlin_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `leroy_merlin_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 `leroy_merlin_list_order_documents`.\n\n**Writes: confirm first.** `leroy_merlin_accept_order`, `leroy_merlin_update_tracking`, `leroy_merlin_ship_order`, `leroy_merlin_resolve_incident`, `leroy_merlin_accept_return`, `leroy_merlin_receive_return`, `leroy_merlin_update_offers`, `leroy_merlin_reply_thread`, `leroy_merlin_create_order_thread` and `leroy_merlin_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. `leroy_merlin_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)**: `leroy_merlin_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 (`leroy_merlin_get_offer` or `leroy_merlin_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 `leroy_merlin_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `leroy_merlin_list_offer_conditions`, logistic class codes from `leroy_merlin_list_logistic_classes`.\n\n**File imports**: `leroy_merlin_import_products` (P41) and `leroy_merlin_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Leroy Merlin asks for; the connector downloads it and uploads it to Leroy Merlin. Track them with `leroy_merlin_list_product_imports` / `leroy_merlin_get_product_import` and `leroy_merlin_list_offer_imports` / `leroy_merlin_get_offer_import`.\n\n**Returns**: `leroy_merlin_list_returns` (RT11) lists return requests. Where Leroy Merlin lets the shop decide, `leroy_merlin_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `leroy_merlin_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `leroy_merlin_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `leroy_merlin_get_thread` reads one with its messages, `leroy_merlin_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Leroy Merlin) and `leroy_merlin_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `leroy_merlin_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `leroy_merlin_list_invoices` (IV01) lists the accounting documents Leroy Merlin issues to the shop and `leroy_merlin_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Leroy Merlin uses Enhanced Seller Invoicing, IV01 returns no new documents; use `leroy_merlin_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 `leroy_merlin_export_offers`, poll `leroy_merlin_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `leroy_merlin_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 `leroy_merlin_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 `leroy_merlin_get_account` and the same `shop_id`. Without `shop_id` a call uses `LEROY_MERLIN_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**: `leroy_merlin_list_channels` (country sites), `leroy_merlin_list_carriers`, `leroy_merlin_list_shipping_zones`, `leroy_merlin_list_shipping_methods` and `leroy_merlin_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 Leroy Merlin can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `leroy_merlin_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`).", diff --git a/packages/backend/src/adapters/intl/minted.json b/packages/backend/src/adapters/intl/minted.json new file mode 100644 index 000000000..918f7013d --- /dev/null +++ b/packages/backend/src/adapters/intl/minted.json @@ -0,0 +1,2031 @@ +{ + "slug": "minted", + "name": "Minted Marketplace", + "aliases": [ + "Minted seller API", + "Minted maker marketplace", + "Minted Direct From Artist", + "Minted Mirakl" + ], + "description": "Run your shop on the Minted 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 Minted seller back office.", + "instructions": "## Minted Marketplace\nRun your shop on the Minted marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Minted, returns, order documents, invoices and transactions. The connector calls the Minted seller platform at `https://mintedus-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**: Minted is curated: makers send an interest form that its merchandising team reviews, then make and ship their own products. Makers keep 75 % of each sale and pay no listing fee. The connector needs a seller account that Minted 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 Minted seller back office: `https://mintedus-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 `MINTED_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 `MINTED_SHOP_ID` empty. Only if your user manages several shops on Minted, set `MINTED_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 `minted_get_account`). Without it your default shop is used.\n4. Install and run `minted_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Minted 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**: `minted_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `minted_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `minted_list_offers` for prices and stock and `minted_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `minted_get_products` looks products up in the Minted catalog by EAN or another reference and returns the marketplace product SKU; `minted_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`. `minted_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `minted_update_tracking` stores the carrier and tracking number (carrier codes come from `minted_list_carriers`) and `minted_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `minted_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `minted_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 `minted_list_order_documents`.\n\n**Writes: confirm first.** `minted_accept_order`, `minted_update_tracking`, `minted_ship_order`, `minted_resolve_incident`, `minted_accept_return`, `minted_receive_return`, `minted_update_offers`, `minted_reply_thread`, `minted_create_order_thread` and `minted_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. `minted_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)**: `minted_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 (`minted_get_offer` or `minted_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 `minted_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `minted_list_offer_conditions`, logistic class codes from `minted_list_logistic_classes`.\n\n**File imports**: `minted_import_products` (P41) and `minted_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Minted asks for; the connector downloads it and uploads it to Minted. Track them with `minted_list_product_imports` / `minted_get_product_import` and `minted_list_offer_imports` / `minted_get_offer_import`.\n\n**Returns**: `minted_list_returns` (RT11) lists return requests. Where Minted lets the shop decide, `minted_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `minted_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `minted_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `minted_get_thread` reads one with its messages, `minted_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Minted) and `minted_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `minted_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `minted_list_invoices` (IV01) lists the accounting documents Minted issues to the shop and `minted_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Minted uses Enhanced Seller Invoicing, IV01 returns no new documents; use `minted_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 `minted_export_offers`, poll `minted_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `minted_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 `minted_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 `minted_get_account` and the same `shop_id`. Without `shop_id` a call uses `MINTED_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**: `minted_list_channels` (country sites), `minted_list_carriers`, `minted_list_shipping_zones`, `minted_list_shipping_methods` and `minted_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 Minted can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `minted_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": "minted", + "docsUrl": "https://www.minted.com/participate/overview", + "requiredEnvVars": [ + "MINTED_API_KEY" + ], + "optionalEnvVars": [ + "MINTED_SHOP_ID" + ], + "prerequisites": "An open seller account with Minted and access to its seller back office to generate the shop API key. Minted is curated: makers send an interest form that its merchandising team reviews, then make and ship their own products. Makers keep 75 % of each sale and pay no listing fee.", + "envVarMeta": { + "MINTED_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Minted 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://mintedus-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "MINTED_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on Minted: 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": "Minted refused the API key. Check that MINTED_API_KEY is the shop key from your Minted 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 MINTED_SHOP_ID to a shop you manage.", + "404": "The Minted seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://mintedus-prod.mirakl.net: Minted may have moved its seller back office.", + "rate_limited": "Minted is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "minted_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 Minted 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 Minted seller account", + "body": "Sign in to the Minted seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Minted seller back office", + "url": "https://mintedus-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 Minted (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": "Minted is curated: makers send an interest form that its merchandising team reviews, then make and ship their own products. Makers keep 75 % of each sale and pay no listing fee. See [the Minted seller page](https://www.minted.com/participate/overview)." + } + ] + }, + { + "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": [ + "MINTED_API_KEY", + "MINTED_SHOP_ID" + ], + "problems": [ + { + "q": "Minted 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": "Minted Marketplace", + "type": "REST", + "baseUrl": "https://mintedus-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{MINTED_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "MINTED_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": "minted_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by minted_update_offers or minted_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 minted_update_offers or minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_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 minted_get_offer_export_status about once a minute until COMPLETED, then read each file with minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "MINTED_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": "minted_get_offer_export_status", + "description": "Status of an offer export started with minted_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 minted_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 Minted 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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "MINTED_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": "minted_list_threads", + "description": "List message threads (M11) with customers and Minted: 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 Minted)." + }, + "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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_list_invoices", + "description": "List the accounting documents Minted 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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "MINTED_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": "minted_list_document_requests", + "description": "List accounting document requests (DR11), used when Minted runs Enhanced Seller Invoicing: invoices and credit notes that Minted 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 Minted (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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_list_orders and minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "minted_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from minted_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 minted_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in minted_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_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": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "minted_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 minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "minted_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Minted. 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 minted_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 (Minted) 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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_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": "minted_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Minted 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 (Minted) 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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_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": "minted_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 minted_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 minted_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "minted_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Minted 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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_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": "MINTED_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": "minted_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 minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "MINTED_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "minted_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 Minted asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with minted_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 Minted 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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "MINTED_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": "minted_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 Minted asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with minted_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 minted_get_account, also shown in the back office). Leave it out to use MINTED_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "MINTED_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/minted.live.spec.ts b/packages/backend/src/adapters/intl/minted.live.spec.ts new file mode 100644 index 000000000..a29bd3b02 --- /dev/null +++ b/packages/backend/src/adapters/intl/minted.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './minted.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_MINTED_LIVE=1 (GET /api/version needs no key; the shop reads need MINTED_API_KEY). +describeRetailerAdapter(adapter, { slug: 'minted', hosts: ['mintedus-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/intl/mirakl.json b/packages/backend/src/adapters/intl/mirakl.json index e790bc36f..b1945bcc9 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**: Åhléns, Atlas For Men, Auchan, B&Q, Best Buy, Black Red White, Bloomingdale's, Boulanger, BrandAlley, Brico Dépôt, Bricomarché, Bunnings, BUT, Carrefour, Conforama, Conrad, Coppel, Cultura, Debenhams, Decathlon, Douglas Partner Program, E.Leclerc, El Corte Inglés, EmpikPlace, ePRICE, Greenweez, H&M Home, home24, HORNBACH, IBS.it, INNO, Jardiland and Gamm vert, Kiabi, Kohl's, La Poste, La Redoute, LDLC, Leen Bakker, Leroy Merlin, Lowe's, Macy's, Maisons du Monde, MediaMarkt, MODIVO, Mountain Warehouse, Nature & Découvertes, Nordstrom, Obelink, 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, 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`).", "region": "intl", "category": "e-commerce", "icon": "mirakl", diff --git a/packages/backend/src/adapters/intl/parts-town.json b/packages/backend/src/adapters/intl/parts-town.json new file mode 100644 index 000000000..f7dd53b3c --- /dev/null +++ b/packages/backend/src/adapters/intl/parts-town.json @@ -0,0 +1,2031 @@ +{ + "slug": "parts-town", + "name": "Parts Town Marketplace", + "aliases": [ + "PartsTown", + "Parts Town seller API", + "Parts Town Marketplace sellers", + "Parts Town Mirakl" + ], + "description": "Run your shop on the Parts Town 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 Parts Town seller back office.", + "instructions": "## Parts Town Marketplace\nRun your shop on the Parts Town marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Parts Town, returns, order documents, invoices and transactions. The connector calls the Parts Town seller platform at `https://partstown-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**: Parts Town approves both the seller and each product; apply by e-mail (`marketplaceteam@partstown.com`). Sellers are suppliers and distributors of genuine OEM parts and other products for foodservice, HVAC, laundry and plumbing technicians; they set their own prices and shipping and ship the orders themselves. There is no sign-up or monthly fee, only a referral fee by category on each sale. The connector needs a seller account that Parts Town 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 Parts Town seller back office: `https://partstown-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 `PARTS_TOWN_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 `PARTS_TOWN_SHOP_ID` empty. Only if your user manages several shops on Parts Town, set `PARTS_TOWN_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 `parts_town_get_account`). Without it your default shop is used.\n4. Install and run `parts_town_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Parts Town 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**: `parts_town_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `parts_town_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `parts_town_list_offers` for prices and stock and `parts_town_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `parts_town_get_products` looks products up in the Parts Town catalog by EAN or another reference and returns the marketplace product SKU; `parts_town_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`. `parts_town_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `parts_town_update_tracking` stores the carrier and tracking number (carrier codes come from `parts_town_list_carriers`) and `parts_town_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `parts_town_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `parts_town_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 `parts_town_list_order_documents`.\n\n**Writes: confirm first.** `parts_town_accept_order`, `parts_town_update_tracking`, `parts_town_ship_order`, `parts_town_resolve_incident`, `parts_town_accept_return`, `parts_town_receive_return`, `parts_town_update_offers`, `parts_town_reply_thread`, `parts_town_create_order_thread` and `parts_town_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. `parts_town_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)**: `parts_town_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 (`parts_town_get_offer` or `parts_town_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 `parts_town_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `parts_town_list_offer_conditions`, logistic class codes from `parts_town_list_logistic_classes`.\n\n**File imports**: `parts_town_import_products` (P41) and `parts_town_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Parts Town asks for; the connector downloads it and uploads it to Parts Town. Track them with `parts_town_list_product_imports` / `parts_town_get_product_import` and `parts_town_list_offer_imports` / `parts_town_get_offer_import`.\n\n**Returns**: `parts_town_list_returns` (RT11) lists return requests. Where Parts Town lets the shop decide, `parts_town_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `parts_town_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `parts_town_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `parts_town_get_thread` reads one with its messages, `parts_town_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Parts Town) and `parts_town_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `parts_town_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `parts_town_list_invoices` (IV01) lists the accounting documents Parts Town issues to the shop and `parts_town_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Parts Town uses Enhanced Seller Invoicing, IV01 returns no new documents; use `parts_town_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 `parts_town_export_offers`, poll `parts_town_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `parts_town_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 `parts_town_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 `parts_town_get_account` and the same `shop_id`. Without `shop_id` a call uses `PARTS_TOWN_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**: `parts_town_list_channels` (country sites), `parts_town_list_carriers`, `parts_town_list_shipping_zones`, `parts_town_list_shipping_methods` and `parts_town_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 Parts Town can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `parts_town_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": "parts-town", + "docsUrl": "https://www.partstown.com/marketplace-sellers", + "requiredEnvVars": [ + "PARTS_TOWN_API_KEY" + ], + "optionalEnvVars": [ + "PARTS_TOWN_SHOP_ID" + ], + "prerequisites": "An open seller account with Parts Town and access to its seller back office to generate the shop API key. Parts Town approves both the seller and each product; apply by e-mail (`marketplaceteam@partstown.com`). Sellers are suppliers and distributors of genuine OEM parts and other products for foodservice, HVAC, laundry and plumbing technicians; they set their own prices and shipping and ship the orders themselves. There is no sign-up or monthly fee, only a referral fee by category on each sale.", + "envVarMeta": { + "PARTS_TOWN_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Parts Town 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://partstown-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "PARTS_TOWN_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on Parts Town: 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": "Parts Town refused the API key. Check that PARTS_TOWN_API_KEY is the shop key from your Parts Town 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 PARTS_TOWN_SHOP_ID to a shop you manage.", + "404": "The Parts Town seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://partstown-prod.mirakl.net: Parts Town may have moved its seller back office.", + "rate_limited": "Parts Town is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "parts_town_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 Parts Town 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 Parts Town seller account", + "body": "Sign in to the Parts Town seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Parts Town seller back office", + "url": "https://partstown-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 Parts Town (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": "Parts Town approves both the seller and each product; apply by e-mail (`marketplaceteam@partstown.com`). Sellers are suppliers and distributors of genuine OEM parts and other products for foodservice, HVAC, laundry and plumbing technicians; they set their own prices and shipping and ship the orders themselves. There is no sign-up or monthly fee, only a referral fee by category on each sale. See [the Parts Town seller page](https://www.partstown.com/marketplace-sellers)." + } + ] + }, + { + "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": [ + "PARTS_TOWN_API_KEY", + "PARTS_TOWN_SHOP_ID" + ], + "problems": [ + { + "q": "Parts Town 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": "Parts Town Marketplace", + "type": "REST", + "baseUrl": "https://partstown-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{PARTS_TOWN_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by parts_town_update_offers or parts_town_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 parts_town_update_offers or parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_get_offer_export_status about once a minute until COMPLETED, then read each file with parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_get_offer_export_status", + "description": "Status of an offer export started with parts_town_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 parts_town_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 Parts Town 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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_list_threads", + "description": "List message threads (M11) with customers and Parts Town: 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 Parts Town)." + }, + "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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_list_invoices", + "description": "List the accounting documents Parts Town 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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_list_document_requests", + "description": "List accounting document requests (DR11), used when Parts Town runs Enhanced Seller Invoicing: invoices and credit notes that Parts Town 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 Parts Town (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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_list_orders and parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "parts_town_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from parts_town_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 parts_town_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in parts_town_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_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": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "parts_town_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 parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "parts_town_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Parts Town. 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 parts_town_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 (Parts Town) 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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_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": "parts_town_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Parts Town 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 (Parts Town) 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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_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": "parts_town_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 parts_town_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 parts_town_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "parts_town_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Parts Town 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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_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": "PARTS_TOWN_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": "parts_town_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 parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "PARTS_TOWN_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "parts_town_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 Parts Town asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with parts_town_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 Parts Town 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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "PARTS_TOWN_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": "parts_town_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 Parts Town asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with parts_town_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 parts_town_get_account, also shown in the back office). Leave it out to use PARTS_TOWN_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "PARTS_TOWN_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/parts-town.live.spec.ts b/packages/backend/src/adapters/intl/parts-town.live.spec.ts new file mode 100644 index 000000000..f012953a4 --- /dev/null +++ b/packages/backend/src/adapters/intl/parts-town.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './parts-town.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_PARTS_TOWN_LIVE=1 (GET /api/version needs no key; the shop reads need PARTS_TOWN_API_KEY). +describeRetailerAdapter(adapter, { slug: 'parts-town', hosts: ['partstown-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/nl/anwb.json b/packages/backend/src/adapters/nl/anwb.json new file mode 100644 index 000000000..379e5267e --- /dev/null +++ b/packages/backend/src/adapters/nl/anwb.json @@ -0,0 +1,2032 @@ +{ + "slug": "anwb", + "name": "ANWB Marketplace", + "aliases": [ + "ANWB webwinkel", + "ANWB seller API", + "ANWB Mirakl", + "ANWB partner", + "anwb.nl marketplace" + ], + "description": "Run your shop on the ANWB 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 Netherlands; sign in with the shop API key from your ANWB seller back office.", + "instructions": "## ANWB Marketplace\nRun your shop on the ANWB marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and ANWB, returns, order documents, invoices and transactions. The connector calls the ANWB seller platform at `https://anwbnl-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 Netherlands.\n\n**Who can sell**: ANWB selects its sellers: write to its partner service (`partnerservice@anwb.nl`). The business must be registered in the Netherlands, offer customer service in Dutch and ship orders within five working days. ANWB charges a monthly fee and a commission per sale. The connector needs a seller account that ANWB 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 ANWB seller back office: `https://anwbnl-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 `ANWB_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 `ANWB_SHOP_ID` empty. Only if your user manages several shops on ANWB, set `ANWB_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 `anwb_get_account`). Without it your default shop is used.\n4. Install and run `anwb_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the ANWB 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**: `anwb_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `anwb_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `anwb_list_offers` for prices and stock and `anwb_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `anwb_get_products` looks products up in the ANWB catalog by EAN or another reference and returns the marketplace product SKU; `anwb_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`. `anwb_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `anwb_update_tracking` stores the carrier and tracking number (carrier codes come from `anwb_list_carriers`) and `anwb_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `anwb_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `anwb_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 `anwb_list_order_documents`.\n\n**Writes: confirm first.** `anwb_accept_order`, `anwb_update_tracking`, `anwb_ship_order`, `anwb_resolve_incident`, `anwb_accept_return`, `anwb_receive_return`, `anwb_update_offers`, `anwb_reply_thread`, `anwb_create_order_thread` and `anwb_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. `anwb_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)**: `anwb_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 (`anwb_get_offer` or `anwb_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 `anwb_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `anwb_list_offer_conditions`, logistic class codes from `anwb_list_logistic_classes`.\n\n**File imports**: `anwb_import_products` (P41) and `anwb_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format ANWB asks for; the connector downloads it and uploads it to ANWB. Track them with `anwb_list_product_imports` / `anwb_get_product_import` and `anwb_list_offer_imports` / `anwb_get_offer_import`.\n\n**Returns**: `anwb_list_returns` (RT11) lists return requests. Where ANWB lets the shop decide, `anwb_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `anwb_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `anwb_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `anwb_get_thread` reads one with its messages, `anwb_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is ANWB) and `anwb_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `anwb_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `anwb_list_invoices` (IV01) lists the accounting documents ANWB issues to the shop and `anwb_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If ANWB uses Enhanced Seller Invoicing, IV01 returns no new documents; use `anwb_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 `anwb_export_offers`, poll `anwb_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `anwb_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 `anwb_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 `anwb_get_account` and the same `shop_id`. Without `shop_id` a call uses `ANWB_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**: `anwb_list_channels` (country sites), `anwb_list_carriers`, `anwb_list_shipping_zones`, `anwb_list_shipping_methods` and `anwb_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 ANWB can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `anwb_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": "nl", + "category": "e-commerce", + "icon": "anwb", + "docsUrl": "https://anwbnl-prod.mirakl.net/login", + "requiredEnvVars": [ + "ANWB_API_KEY" + ], + "optionalEnvVars": [ + "ANWB_SHOP_ID" + ], + "prerequisites": "An open seller account with ANWB and access to its seller back office to generate the shop API key. ANWB selects its sellers: write to its partner service (`partnerservice@anwb.nl`). The business must be registered in the Netherlands, offer customer service in Dutch and ship orders within five working days. ANWB charges a monthly fee and a commission per sale.", + "envVarMeta": { + "ANWB_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "ANWB 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://anwbnl-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "ANWB_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on ANWB: 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": "ANWB refused the API key. Check that ANWB_API_KEY is the shop key from your ANWB 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 ANWB_SHOP_ID to a shop you manage.", + "404": "The ANWB seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://anwbnl-prod.mirakl.net: ANWB may have moved its seller back office.", + "rate_limited": "ANWB is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "anwb_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 ANWB 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 ANWB seller account", + "body": "Sign in to the ANWB seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the ANWB seller back office", + "url": "https://anwbnl-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 ANWB (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": "ANWB selects its sellers: write to its partner service (`partnerservice@anwb.nl`). The business must be registered in the Netherlands, offer customer service in Dutch and ship orders within five working days. ANWB charges a monthly fee and a commission per sale." + } + ] + }, + { + "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": [ + "ANWB_API_KEY", + "ANWB_SHOP_ID" + ], + "problems": [ + { + "q": "ANWB 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": "ANWB Marketplace", + "type": "REST", + "baseUrl": "https://anwbnl-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{ANWB_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by anwb_update_offers or anwb_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 anwb_update_offers or anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_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 anwb_get_offer_export_status about once a minute until COMPLETED, then read each file with anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_get_offer_export_status", + "description": "Status of an offer export started with anwb_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 anwb_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 ANWB 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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_list_threads", + "description": "List message threads (M11) with customers and ANWB: 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 ANWB)." + }, + "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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_list_invoices", + "description": "List the accounting documents ANWB 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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_list_document_requests", + "description": "List accounting document requests (DR11), used when ANWB runs Enhanced Seller Invoicing: invoices and credit notes that ANWB 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 ANWB (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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_list_orders and anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "anwb_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from anwb_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 anwb_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in anwb_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_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": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "anwb_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 anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "anwb_reply_thread", + "description": "Reply in a message thread (M12) to the customer or ANWB. 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 anwb_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 (ANWB) 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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_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": "anwb_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, ANWB 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 (ANWB) 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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_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": "anwb_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 anwb_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 anwb_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "anwb_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when ANWB 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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_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": "ANWB_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": "anwb_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 anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "ANWB_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "anwb_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 ANWB asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with anwb_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 ANWB 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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "ANWB_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": "anwb_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 ANWB asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with anwb_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 anwb_get_account, also shown in the back office). Leave it out to use ANWB_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "ANWB_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/nl/anwb.live.spec.ts b/packages/backend/src/adapters/nl/anwb.live.spec.ts new file mode 100644 index 000000000..0fe395a1c --- /dev/null +++ b/packages/backend/src/adapters/nl/anwb.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './anwb.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_ANWB_LIVE=1 (GET /api/version needs no key; the shop reads need ANWB_API_KEY). +describeRetailerAdapter(adapter, { slug: 'anwb', hosts: ['anwbnl-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/nl/kruidvat.json b/packages/backend/src/adapters/nl/kruidvat.json new file mode 100644 index 000000000..b299896d2 --- /dev/null +++ b/packages/backend/src/adapters/nl/kruidvat.json @@ -0,0 +1,2032 @@ +{ + "slug": "kruidvat", + "name": "Kruidvat Marketplace", + "aliases": [ + "Kruidvat seller API", + "Kruidvat partner", + "kruidvat.nl marketplace", + "Kruidvat Mirakl", + "A.S. Watson" + ], + "description": "Run your shop on the Kruidvat 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 Netherlands; sign in with the shop API key from your Kruidvat seller back office.", + "instructions": "## Kruidvat Marketplace\nRun your shop on the Kruidvat marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Kruidvat, returns, order documents, invoices and transactions. The connector calls the Kruidvat seller platform at `https://kruidvatnl-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 Netherlands.\n\n**Who can sell**: Kruidvat selects its sellers and reviews each application, including service levels and the product selection. There is no setup or monthly fee, only a commission per sale that depends on the product type. Partner items are sold online only, and the seller ships every order. The connector needs a seller account that Kruidvat 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 Kruidvat seller back office: `https://kruidvatnl-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 `KRUIDVAT_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 `KRUIDVAT_SHOP_ID` empty. Only if your user manages several shops on Kruidvat, set `KRUIDVAT_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 `kruidvat_get_account`). Without it your default shop is used.\n4. Install and run `kruidvat_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Kruidvat 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**: `kruidvat_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `kruidvat_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `kruidvat_list_offers` for prices and stock and `kruidvat_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `kruidvat_get_products` looks products up in the Kruidvat catalog by EAN or another reference and returns the marketplace product SKU; `kruidvat_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`. `kruidvat_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `kruidvat_update_tracking` stores the carrier and tracking number (carrier codes come from `kruidvat_list_carriers`) and `kruidvat_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `kruidvat_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `kruidvat_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 `kruidvat_list_order_documents`.\n\n**Writes: confirm first.** `kruidvat_accept_order`, `kruidvat_update_tracking`, `kruidvat_ship_order`, `kruidvat_resolve_incident`, `kruidvat_accept_return`, `kruidvat_receive_return`, `kruidvat_update_offers`, `kruidvat_reply_thread`, `kruidvat_create_order_thread` and `kruidvat_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. `kruidvat_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)**: `kruidvat_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 (`kruidvat_get_offer` or `kruidvat_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 `kruidvat_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `kruidvat_list_offer_conditions`, logistic class codes from `kruidvat_list_logistic_classes`.\n\n**File imports**: `kruidvat_import_products` (P41) and `kruidvat_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Kruidvat asks for; the connector downloads it and uploads it to Kruidvat. Track them with `kruidvat_list_product_imports` / `kruidvat_get_product_import` and `kruidvat_list_offer_imports` / `kruidvat_get_offer_import`.\n\n**Returns**: `kruidvat_list_returns` (RT11) lists return requests. Where Kruidvat lets the shop decide, `kruidvat_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `kruidvat_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `kruidvat_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `kruidvat_get_thread` reads one with its messages, `kruidvat_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Kruidvat) and `kruidvat_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `kruidvat_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `kruidvat_list_invoices` (IV01) lists the accounting documents Kruidvat issues to the shop and `kruidvat_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Kruidvat uses Enhanced Seller Invoicing, IV01 returns no new documents; use `kruidvat_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 `kruidvat_export_offers`, poll `kruidvat_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `kruidvat_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 `kruidvat_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 `kruidvat_get_account` and the same `shop_id`. Without `shop_id` a call uses `KRUIDVAT_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**: `kruidvat_list_channels` (country sites), `kruidvat_list_carriers`, `kruidvat_list_shipping_zones`, `kruidvat_list_shipping_methods` and `kruidvat_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 Kruidvat can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `kruidvat_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": "nl", + "category": "e-commerce", + "icon": "kruidvat", + "docsUrl": "https://kruidvatnl-prod.mirakl.net/login", + "requiredEnvVars": [ + "KRUIDVAT_API_KEY" + ], + "optionalEnvVars": [ + "KRUIDVAT_SHOP_ID" + ], + "prerequisites": "An open seller account with Kruidvat and access to its seller back office to generate the shop API key. Kruidvat selects its sellers and reviews each application, including service levels and the product selection. There is no setup or monthly fee, only a commission per sale that depends on the product type. Partner items are sold online only, and the seller ships every order.", + "envVarMeta": { + "KRUIDVAT_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Kruidvat 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://kruidvatnl-prod.mirakl.net/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "KRUIDVAT_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Only when your user manages several shops on Kruidvat: 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": "Kruidvat refused the API key. Check that KRUIDVAT_API_KEY is the shop key from your Kruidvat 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 KRUIDVAT_SHOP_ID to a shop you manage.", + "404": "The Kruidvat seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://kruidvatnl-prod.mirakl.net: Kruidvat may have moved its seller back office.", + "rate_limited": "Kruidvat is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "kruidvat_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 Kruidvat 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 Kruidvat seller account", + "body": "Sign in to the Kruidvat seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Kruidvat seller back office", + "url": "https://kruidvatnl-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 Kruidvat (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": "Kruidvat selects its sellers and reviews each application, including service levels and the product selection. There is no setup or monthly fee, only a commission per sale that depends on the product type. Partner items are sold online only, and the seller ships every order." + } + ] + }, + { + "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": [ + "KRUIDVAT_API_KEY", + "KRUIDVAT_SHOP_ID" + ], + "problems": [ + { + "q": "Kruidvat 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": "Kruidvat Marketplace", + "type": "REST", + "baseUrl": "https://kruidvatnl-prod.mirakl.net/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{KRUIDVAT_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by kruidvat_update_offers or kruidvat_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 kruidvat_update_offers or kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_get_offer_export_status about once a minute until COMPLETED, then read each file with kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_get_offer_export_status", + "description": "Status of an offer export started with kruidvat_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 kruidvat_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 Kruidvat 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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_list_threads", + "description": "List message threads (M11) with customers and Kruidvat: 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 Kruidvat)." + }, + "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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_list_invoices", + "description": "List the accounting documents Kruidvat 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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_list_document_requests", + "description": "List accounting document requests (DR11), used when Kruidvat runs Enhanced Seller Invoicing: invoices and credit notes that Kruidvat 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 Kruidvat (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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_list_orders and kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "kruidvat_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from kruidvat_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 kruidvat_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in kruidvat_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_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": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "kruidvat_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 kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "kruidvat_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Kruidvat. 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 kruidvat_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 (Kruidvat) 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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_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": "kruidvat_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Kruidvat 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 (Kruidvat) 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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_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": "kruidvat_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 kruidvat_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 kruidvat_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "kruidvat_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Kruidvat 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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_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": "KRUIDVAT_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": "kruidvat_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 kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "KRUIDVAT_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "kruidvat_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 Kruidvat asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with kruidvat_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 Kruidvat 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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "KRUIDVAT_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": "kruidvat_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 Kruidvat asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with kruidvat_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 kruidvat_get_account, also shown in the back office). Leave it out to use KRUIDVAT_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "KRUIDVAT_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/nl/kruidvat.live.spec.ts b/packages/backend/src/adapters/nl/kruidvat.live.spec.ts new file mode 100644 index 000000000..d2bb995ed --- /dev/null +++ b/packages/backend/src/adapters/nl/kruidvat.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './kruidvat.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_KRUIDVAT_LIVE=1 (GET /api/version needs no key; the shop reads need KRUIDVAT_API_KEY). +describeRetailerAdapter(adapter, { slug: 'kruidvat', hosts: ['kruidvatnl-prod.mirakl.net'] }); diff --git a/packages/backend/src/adapters/no/elkjop.json b/packages/backend/src/adapters/no/elkjop.json new file mode 100644 index 000000000..edb5569bc --- /dev/null +++ b/packages/backend/src/adapters/no/elkjop.json @@ -0,0 +1,2034 @@ +{ + "slug": "elkjop", + "name": "Elkjøp Marketplace", + "aliases": [ + "Elkjøp Nordic", + "Elgiganten", + "Elgiganten Marketplace", + "Gigantti", + "Elkjøp seller API", + "Elkjøp Mirakl", + "partner.elkjopnordic.com" + ], + "description": "Run your shop on the Elkjøp 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 Norway, Sweden, Denmark and Finland; sign in with the shop API key from your Elkjøp seller back office.", + "instructions": "## Elkjøp Marketplace\nRun your shop on the Elkjøp marketplace from an AI agent: orders, acceptance, tracking and shipping, incidents, offers with prices and stock, offer and product imports, messages with customers and Elkjøp, returns, order documents, invoices and transactions. The connector calls the Elkjøp seller platform at `https://partner.elkjopnordic.com` with the API key of your shop, so it can see and do what your seller user can.\n\n**Countries**: Norway, Sweden, Denmark and Finland. The marketplace trades as Elkjøp in Norway, Elgiganten in Sweden and Denmark and Gigantti in Finland.\n\n**Who can sell**: Elkjøp selects its partners: apply through its marketplace partner page and Elkjøp reviews the application. Partners are Nordic or European suppliers that keep their own stock and ship each order themselves; product texts are needed in the language of each country. The connector needs a seller account that Elkjøp has already opened.\n\nTo switch country in the seller back office, use the selector at the top right; each country shows its own shop id under My account > Settings.\n\n**Setup (about 5 minutes)**\n1. Sign in to the Elkjøp seller back office: `https://partner.elkjopnordic.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 `ELKJOP_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. Elkjøp opens one shop per country under the same user; the API key is the same, the shop id picks the country. If your user has more than one shop, set `ELKJOP_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 `elkjop_get_account`); to work on several shops, install the connector once per shop. Without it your default shop is used.\n4. Install and run `elkjop_get_account`: it returns the shop the key belongs to.\n\n**Platform**: the Elkjøp 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**: `elkjop_get_account` shows the shop behind the key (id, name, state, currency and channels). For the daily work use `elkjop_list_orders` with `order_state_codes=WAITING_ACCEPTANCE`, `elkjop_list_offers` for prices and stock and `elkjop_list_threads` for messages that wait for a reply.\n\n**Products and competing offers**: `elkjop_get_products` looks products up in the Elkjøp catalog by EAN or another reference and returns the marketplace product SKU; `elkjop_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`. `elkjop_accept_order` accepts (or refuses) every line; after the customer is debited the order moves to `SHIPPING`. Then `elkjop_update_tracking` stores the carrier and tracking number (carrier codes come from `elkjop_list_carriers`) and `elkjop_ship_order` confirms the shipment (`SHIPPED`). Later states are `TO_COLLECT`, `RECEIVED`, `CLOSED`, `REFUSED` and `CANCELED`. Use `elkjop_list_orders` with `order_state_codes=WAITING_ACCEPTANCE` for the daily to-do list and `has_incident=true` for open incidents; `elkjop_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 `elkjop_list_order_documents`.\n\n**Writes: confirm first.** `elkjop_accept_order`, `elkjop_update_tracking`, `elkjop_ship_order`, `elkjop_resolve_incident`, `elkjop_accept_return`, `elkjop_receive_return`, `elkjop_update_offers`, `elkjop_reply_thread`, `elkjop_create_order_thread` and `elkjop_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. `elkjop_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)**: `elkjop_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 (`elkjop_get_offer` or `elkjop_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 `elkjop_get_offer_import` before reading the offer again. Condition codes for `state_code` come from `elkjop_list_offer_conditions`, logistic class codes from `elkjop_list_logistic_classes`.\n\n**File imports**: `elkjop_import_products` (P41) and `elkjop_import_offers` (OF01) take the URL of a CSV, XLSX or XML file in the file format Elkjøp asks for; the connector downloads it and uploads it to Elkjøp. Track them with `elkjop_list_product_imports` / `elkjop_get_product_import` and `elkjop_list_offer_imports` / `elkjop_get_offer_import`.\n\n**Returns**: `elkjop_list_returns` (RT11) lists return requests. Where Elkjøp lets the shop decide, `elkjop_accept_return` accepts or refuses one in `WAITING_ACCEPTANCE` and `elkjop_receive_return` confirms the goods arrived. Refunds stay in the back office.\n\n**Messages**: `elkjop_list_threads` lists conversations (filter with `entity_type=MMP_ORDER` and `entity_id=` for one order; `entity_id` without `entity_type` is refused), `elkjop_get_thread` reads one with its messages, `elkjop_reply_thread` answers (recipient `CUSTOMER` or `OPERATOR`, which is Elkjøp) and `elkjop_create_order_thread` opens a new conversation on an order. Reason codes for topics come from `elkjop_list_reasons`; leave its `locale` empty unless you know the marketplace has that language (an inactive locale answers 400).\n\n**Money**: `elkjop_list_invoices` (IV01) lists the accounting documents Elkjøp issues to the shop and `elkjop_list_transactions` (TL02) the transaction lines (sales, commissions, refunds, payouts). If Elkjøp uses Enhanced Seller Invoicing, IV01 returns no new documents; use `elkjop_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 `elkjop_export_offers`, poll `elkjop_get_offer_export_status` about once a minute until it is `COMPLETED`, and read the files one by one with `elkjop_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 `elkjop_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 `elkjop_get_account` and the same `shop_id`. Without `shop_id` a call uses `ELKJOP_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**: `elkjop_list_channels` (country sites), `elkjop_list_carriers`, `elkjop_list_shipping_zones`, `elkjop_list_shipping_methods` and `elkjop_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 Elkjøp can tighten them. Listing offers and orders is meant for interactive use, product and offer imports at most every 15 minutes, `elkjop_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": "no", + "category": "e-commerce", + "icon": "elkjop", + "docsUrl": "https://www.elgiganten.se/partner/elgiganten-marketplace-partner", + "requiredEnvVars": [ + "ELKJOP_API_KEY" + ], + "optionalEnvVars": [ + "ELKJOP_SHOP_ID" + ], + "prerequisites": "An open seller account with Elkjøp and access to its seller back office to generate the shop API key. Elkjøp selects its partners: apply through its marketplace partner page and Elkjøp reviews the application. Partners are Nordic or European suppliers that keep their own stock and ship each order themselves; product texts are needed in the language of each country.", + "envVarMeta": { + "ELKJOP_API_KEY": { + "label": "Shop API key", + "kind": "credential", + "secret": true, + "help": "Elkjøp 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://partner.elkjopnordic.com/login", + "pattern": "^[A-Za-z0-9_-]{16,128}$", + "patternMessage": "Paste the API key alone, without Bearer, quotes or spaces." + }, + "ELKJOP_SHOP_ID": { + "label": "Shop ID (optional)", + "kind": "setting", + "help": "Elkjøp opens one shop per country under the same user; the API key is the same, the shop id picks the country. With more than one shop, enter the numeric id of the shop to use (on the back office dashboard, next to Identifier or Shop ID). Leave empty to use your default shop.", + "example": "2001", + "pattern": "^[0-9]+$", + "patternMessage": "The shop id is a number." + } + }, + "verifyHints": { + "401": "Elkjøp refused the API key. Check that ELKJOP_API_KEY is the shop key from your Elkjøp 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 ELKJOP_SHOP_ID to a shop you manage.", + "404": "The Elkjøp seller platform did not find this for your shop. If every call answers this way, compare the address you sign in at with https://partner.elkjopnordic.com: Elkjøp may have moved its seller back office.", + "rate_limited": "Elkjøp is rate limiting this API for your shop. Wait for the seconds in the Retry-After header before trying again." + }, + "probe": { + "tool": "elkjop_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 Elkjøp 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 Elkjøp seller account", + "body": "Sign in to the Elkjøp seller back office. Then open the menu below and create a key, or copy the one that is already there.", + "action": { + "label": "Open the Elkjøp seller back office", + "url": "https://partner.elkjopnordic.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 Elkjøp (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": "Elkjøp selects its partners: apply through its marketplace partner page and Elkjøp reviews the application. Partners are Nordic or European suppliers that keep their own stock and ship each order themselves; product texts are needed in the language of each country. See [the Elkjøp seller page](https://www.elgiganten.se/partner/elgiganten-marketplace-partner)." + } + ] + }, + { + "id": "api-key", + "title": "Paste the key", + "body": "Paste the key alone, without `Bearer`, quotes or spaces. Elkjøp opens one shop per country under the same user; the API key is the same, the shop id picks the country. If your user has more than one shop, also enter the id of the shop to use.", + "fields": [ + "ELKJOP_API_KEY", + "ELKJOP_SHOP_ID" + ], + "problems": [ + { + "q": "Elkjøp 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": "Elkjøp Marketplace", + "type": "REST", + "baseUrl": "https://partner.elkjopnordic.com/api", + "authType": "API_KEY", + "authConfig": { + "headerName": "Authorization", + "apiKey": "{{ELKJOP_API_KEY}}" + }, + "headers": { + "Accept": "application/json" + } + }, + "tools": [ + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/account", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/orders", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_update_offers, which needs the complete offer.", + "parameters": { + "type": "object", + "properties": { + "offer_id": { + "type": "integer", + "description": "Offer id on the marketplace (offer_id in elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/states", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_list_offer_imports", + "description": "List offer imports and updates (OF04), from files and from elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_get_offer_import", + "description": "Read the status of one offer import or offer update (OF02) by its import_id, as returned by elkjop_update_offers or elkjop_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 elkjop_update_offers or elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_get_offer_export_status about once a minute until COMPLETED, then read each file with elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/export/async", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_get_offer_export_status", + "description": "Status of an offer export started with elkjop_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 elkjop_get_offer_export_file.", + "parameters": { + "type": "object", + "properties": { + "tracking_id": { + "type": "string", + "description": "tracking_id returned by elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "file": "$file", + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/imports", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "status": "$status", + "last_request_date": "$last_request_date", + "max": "$max", + "offset": "$offset", + "order": "$order", + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 Elkjøp 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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "product_references" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/products", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "product_references": "$product_references", + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/products/offers", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_list_threads", + "description": "List message threads (M11) with customers and Elkjøp: 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 Elkjøp)." + }, + "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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/inbox/threads", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/returns", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/reasons", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "locale": "$locale", + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_list_carriers", + "description": "List the carriers the marketplace knows (SH21) with their code, label and tracking URL. Use the code as carrier_code in elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/carriers", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_list_invoices", + "description": "List the accounting documents Elkjøp 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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/invoices", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/sellerpayment/transactions_logs", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_list_document_requests", + "description": "List accounting document requests (DR11), used when Elkjøp runs Enhanced Seller Invoicing: invoices and credit notes that Elkjøp 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 Elkjøp (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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/document-request/requests", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "order_ids" + ] + }, + "endpointMapping": { + "method": "GET", + "path": "/orders/documents", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "order_ids": "$order_ids", + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_list_orders and elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/channels", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/zones", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/types", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + } + }, + "endpointMapping": { + "method": "GET", + "path": "/shipping/logistic_classes", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + } + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "order_lines": "$order_lines" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "elkjop_update_tracking", + "description": "Set the carrier and tracking number of an order (OR23). Give carrier_code from elkjop_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 elkjop_list_carriers." + }, + "carrier_name": { + "type": "string", + "description": "Carrier name, for a carrier that is not in elkjop_list_carriers." + }, + "carrier_url": { + "type": "string", + "description": "Full tracking URL, for a carrier that is not in elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_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": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "elkjop_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 elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "offers" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "offers": "$offers" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "elkjop_reply_thread", + "description": "Reply in a message thread (M12) to the customer or Elkjøp. 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 elkjop_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 (Elkjøp) 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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_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": "elkjop_create_order_thread", + "description": "Start a new message thread on an order (OR43) with the customer, Elkjøp 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 (Elkjøp) 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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_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": "elkjop_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 elkjop_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 elkjop_list_orders)." + }, + "reason_code": { + "type": "string", + "description": "Code of an INCIDENT_CLOSE reason from elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_SHOP_ID" + }, + "encodePathParams": true, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "reason_code": "$reason_code" + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "elkjop_accept_return", + "description": "Accept or refuse a return request in WAITING_ACCEPTANCE (RT21). Only when Elkjøp 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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_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": "ELKJOP_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": "elkjop_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 elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "return_id" + ] + }, + "endpointMapping": { + "method": "PUT", + "path": "/returns/receive", + "envDefaults": { + "shop_id": "ELKJOP_SHOP_ID" + }, + "queryParams": { + "shop_id": "$shop_id" + }, + "bodyMapping": { + "returns": [ + { + "id": "$return_id" + } + ] + } + }, + "annotations": { + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": true + } + }, + { + "name": "elkjop_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 Elkjøp asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with elkjop_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 Elkjøp 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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/products/imports", + "envDefaults": { + "shop_id": "ELKJOP_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": "elkjop_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 Elkjøp asks for; the connector downloads it (up to 10 MB) and uploads it. Returns an import_id to follow with elkjop_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 elkjop_get_account, also shown in the back office). Leave it out to use ELKJOP_SHOP_ID, or the user's default shop when that is empty." + } + }, + "required": [ + "file_url" + ] + }, + "endpointMapping": { + "method": "POST", + "path": "/offers/imports", + "envDefaults": { + "shop_id": "ELKJOP_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/no/elkjop.live.spec.ts b/packages/backend/src/adapters/no/elkjop.live.spec.ts new file mode 100644 index 000000000..8aa62f56a --- /dev/null +++ b/packages/backend/src/adapters/no/elkjop.live.spec.ts @@ -0,0 +1,6 @@ +import * as adapter from './elkjop.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_ELKJOP_LIVE=1 (GET /api/version needs no key; the shop reads need ELKJOP_API_KEY). +describeRetailerAdapter(adapter, { slug: 'elkjop', hosts: ['partner.elkjopnordic.com'] }); diff --git a/packages/frontend/public/logos/connectors/anwb.svg b/packages/frontend/public/logos/connectors/anwb.svg new file mode 100644 index 000000000..637b8fadc --- /dev/null +++ b/packages/frontend/public/logos/connectors/anwb.svg @@ -0,0 +1,4 @@ + + + AN + diff --git a/packages/frontend/public/logos/connectors/casa-del-libro.svg b/packages/frontend/public/logos/connectors/casa-del-libro.svg new file mode 100644 index 000000000..c0dc1f4c0 --- /dev/null +++ b/packages/frontend/public/logos/connectors/casa-del-libro.svg @@ -0,0 +1,4 @@ + + + CL + diff --git a/packages/frontend/public/logos/connectors/elkjop.svg b/packages/frontend/public/logos/connectors/elkjop.svg new file mode 100644 index 000000000..502b0bdc1 --- /dev/null +++ b/packages/frontend/public/logos/connectors/elkjop.svg @@ -0,0 +1,4 @@ + + + El + diff --git a/packages/frontend/public/logos/connectors/flowers-1800.svg b/packages/frontend/public/logos/connectors/flowers-1800.svg new file mode 100644 index 000000000..bc38fba74 --- /dev/null +++ b/packages/frontend/public/logos/connectors/flowers-1800.svg @@ -0,0 +1,4 @@ + + + 18 + diff --git a/packages/frontend/public/logos/connectors/fressnapf.svg b/packages/frontend/public/logos/connectors/fressnapf.svg new file mode 100644 index 000000000..0ee4d3242 --- /dev/null +++ b/packages/frontend/public/logos/connectors/fressnapf.svg @@ -0,0 +1,4 @@ + + + Fr + diff --git a/packages/frontend/public/logos/connectors/gacd.svg b/packages/frontend/public/logos/connectors/gacd.svg new file mode 100644 index 000000000..5e21cde22 --- /dev/null +++ b/packages/frontend/public/logos/connectors/gacd.svg @@ -0,0 +1,4 @@ + + + GA + diff --git a/packages/frontend/public/logos/connectors/kruidvat.svg b/packages/frontend/public/logos/connectors/kruidvat.svg new file mode 100644 index 000000000..55f8bbd04 --- /dev/null +++ b/packages/frontend/public/logos/connectors/kruidvat.svg @@ -0,0 +1,4 @@ + + + Kv + diff --git a/packages/frontend/public/logos/connectors/minted.svg b/packages/frontend/public/logos/connectors/minted.svg new file mode 100644 index 000000000..98ef21e6b --- /dev/null +++ b/packages/frontend/public/logos/connectors/minted.svg @@ -0,0 +1,4 @@ + + + Mi + diff --git a/packages/frontend/public/logos/connectors/parts-town.svg b/packages/frontend/public/logos/connectors/parts-town.svg new file mode 100644 index 000000000..577de8b55 --- /dev/null +++ b/packages/frontend/public/logos/connectors/parts-town.svg @@ -0,0 +1,4 @@ + + + PT + diff --git a/scripts/generate-retailer-adapters.mjs b/scripts/generate-retailer-adapters.mjs index 96af26d83..9b9e9720a 100644 --- a/scripts/generate-retailer-adapters.mjs +++ b/scripts/generate-retailer-adapters.mjs @@ -39,7 +39,7 @@ 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 = '09ed84df109c15dc282e299185074615f74e66acaffad034a665275ca4dcd7d5'; +const REVIEWED_SOURCE_SHA256 = '9e803eb5a80a369b9b065009b30944f36a9308f0126684d2e5f8d7d0b6ef1940'; const COUNTRY = { AT: 'Austria', BE: 'Belgium', CA: 'Canada', CH: 'Switzerland', CZ: 'the Czech Republic', DE: 'Germany', diff --git a/scripts/retailer-marketplaces.json b/scripts/retailer-marketplaces.json index d307fe0d9..826d97596 100644 --- a/scripts/retailer-marketplaces.json +++ b/scripts/retailer-marketplaces.json @@ -109,7 +109,7 @@ "notes": [ "Leroy Merlin Poland (a separate shop in PLN) and Romania run on other addresses, which this connector does not reach." ], - "aliases": ["Leroy Merlin seller API", "Leroy Merlin Mirakl", "ADEO Marketplace", "Bricoman"], + "aliases": ["Leroy Merlin seller API", "Leroy Merlin Mirakl", "ADEO Marketplace", "Bricoman", "Tecnomat"], "sources": [ "https://github.com/KPFranceSAS/integration-channel/blob/HEAD/.env", "https://github.com/Ventmere/mirakl/blob/HEAD/mirakl/src/lib.rs", @@ -1674,6 +1674,229 @@ "https://www.mirakl.com/blog/saloncentric-partners-with-mirakl-to-offer-stylists-a-whole-new-way-to-shop", "https://www.probeautycentral.saloncentric.com/marketplace" ] + }, + { + "slug": "elkjop", + "name": "Elkjøp Marketplace", + "retailer": "Elkjøp", + "region": "no", + "brandColor": "#11175E", + "monogram": "El", + "hosts": [{ "value": "https://partner.elkjopnordic.com", "label": "Norway, Sweden, Denmark and Finland" }], + "countries": ["NO", "SE", "DK", "FI"], + "countriesNote": "The marketplace trades as Elkjøp in Norway, Elgiganten in Sweden and Denmark and Gigantti in Finland.", + "shopIdNeeded": true, + "shopIdNote": "Elkjøp opens one shop per country under the same user; the API key is the same, the shop id picks the country.", + "access": "Elkjøp selects its partners: apply through its marketplace partner page and Elkjøp reviews the application. Partners are Nordic or European suppliers that keep their own stock and ship each order themselves; product texts are needed in the language of each country.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": "https://www.elgiganten.se/partner/elgiganten-marketplace-partner", + "notes": [ + "To switch country in the seller back office, use the selector at the top right; each country shows its own shop id under My account > Settings." + ], + "aliases": ["Elkjop", "Elkjøp Nordic", "Elgiganten", "Elgiganten Marketplace", "Gigantti", "Elkjøp seller API", "Elkjøp Mirakl", "partner.elkjopnordic.com"], + "sources": [ + "https://support.sello.io/hc/en-us/articles/360010747799-Connecting-to-Elkj%C3%B8p-Nordic", + "https://support.sello.io/hc/en-us/articles/20754680385170", + "https://support.sello.io/hc/en-us/articles/9166941418898-Trigger-a-full-offer-export-for-a-Mirakl-marketplace", + "https://e-tailize.com/integrations/selling-on-elkjop/", + "https://www.mirakl.com/blogs/marketplace/elkjops-marketplace-scaling-secret-knowing-what-not-to-own/" + ] + }, + { + "slug": "casa-del-libro", + "name": "Casa del Libro Marketplace", + "retailer": "Casa del Libro", + "region": "es", + "brandColor": "#004D43", + "monogram": "CL", + "hosts": [{ "value": "https://marketplace.casadellibro.com", "label": "Spain" }], + "countries": ["ES"], + "shopIdNeeded": false, + "access": "Casa del Libro reviews each seller application. It has two seller plans: a professional plan with a monthly fee, charged only in months with sales, and an individual plan with a fixed fee per item sold; both pay a 15% commission. Offers attach to products already in the Casa del Libro catalogue, and only the professional plan can create missing products. Sellers ship each order themselves within a 3 to 5 day delivery window.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": null, + "notes": [], + "aliases": ["Casa del Libro seller API", "Casa del Libro vendedores", "casadellibro.com marketplace", "Casa del Libro Mirakl", "Grupo Planeta", "CDL marketplace"], + "sources": [ + "https://crt.sh/?q=%25.casadellibro.com", + "https://www.mirakl.com/news/casa-del-libro-launches-new-online-marketplace/", + "https://apps.odoo.com/apps/modules/19.0/cognisance_casa_del_libro", + "https://e-tailize.com/integrations/casa-del-libro/", + "https://github.com/DavisGalla/products-api-push/blob/2ae855fe8c87c320a6b605b0dc17028ea0eb9092/casadellibro_push.py" + ] + }, + { + "slug": "gacd", + "name": "GACD Marketplace", + "retailer": "GACD", + "region": "fr", + "brandColor": "#1A1A1A", + "monogram": "GA", + "hosts": [{ "value": "https://tdmp.mirakl.net", "label": "France" }], + "countries": ["FR"], + "shopIdNeeded": false, + "access": "GACD opens seller accounts on request: contact its sales team. The marketplace sells to dental practices in France, from dental supplies and equipment to furniture and office products, and GACD only accepts products with an EAN.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": null, + "notes": [], + "aliases": ["GACD seller API", "GACD marketplace dentaire", "The Dental Marketplace", "TDMP", "GACD Mirakl", "tdmp.mirakl.net"], + "sources": [ + "https://github.com/Ventmere/mirakl/blob/HEAD/mirakl/src/lib.rs", + "https://apps.odoo.com/apps/modules/19.0/flexigobe_mirakl_provider_gacd", + "https://help.beezup.com/en/articles/5796599-gacd-products-publication", + "https://base.com/en-IN/integrations/gacdfr/", + "https://www.edesk.com/appstore/gacd/" + ] + }, + { + "slug": "anwb", + "name": "ANWB Marketplace", + "retailer": "ANWB", + "region": "nl", + "brandColor": "#FEDC00", + "letterColor": "#003D86", + "monogram": "AN", + "hosts": [{ "value": "https://anwbnl-prod.mirakl.net", "label": "Netherlands" }], + "countries": ["NL"], + "shopIdNeeded": false, + "access": "ANWB selects its sellers: write to its partner service (`partnerservice@anwb.nl`). The business must be registered in the Netherlands, offer customer service in Dutch and ship orders within five working days. ANWB charges a monthly fee and a commission per sale.", + "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": ["ANWB webwinkel", "ANWB seller API", "ANWB Mirakl", "ANWB partner", "anwb.nl marketplace"], + "sources": [ + "https://support.channelengine.com/hc/en-us/articles/20986607112477-ANWB-marketplace-guide", + "https://e-tailize.com/help/marketplaces/sell-on-anwb/", + "https://e-tailize.com/integrations/anwb/" + ] + }, + { + "slug": "fressnapf", + "name": "Fressnapf Marketplace", + "retailer": "Fressnapf", + "region": "de", + "brandColor": "#00652D", + "monogram": "Fr", + "hosts": [{ "value": "https://fressnapfde-prod.mirakl.net", "label": "Germany and Austria" }], + "countries": ["DE", "AT"], + "countriesNote": "The marketplace opened on fressnapf.de in 2022 and on fressnapf.at in 2024.", + "shopIdNeeded": true, + "shopIdNote": "A seller in both Germany and Austria may have one shop per country under the same user; the shop id picks the shop.", + "access": "Fressnapf selects its partners through the contact form on its marketplace page, which asks for the addresses of your other marketplace shops, the number of articles and whether an integrator connects you. Partners ship their own orders and take back their own returns.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": "https://www.fressnapf.de/marktplatz/", + "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": ["Fressnapf Marktplatz", "Fressnapf seller API", "Fressnapf Partner", "fressnapf.de", "fressnapf.at", "Fressnapf Mirakl"], + "sources": [ + "https://www.fressnapf.de/marktplatz/", + "https://www.fressnapf.at/marktplatz/", + "https://www.mirakl.com/news/fressnapf-group-launches-mirakl-powered-marketplace/", + "https://petworldwide.net/content-1/news/2024/10/31/fressnapf-opens-online-marketplace.html", + "https://e-tailize.com/integrations/selling-on-fressnapf/", + "https://apps.odoo.com/apps/modules/19.0/cognisance_fressnapf" + ] + }, + { + "slug": "kruidvat", + "name": "Kruidvat Marketplace", + "retailer": "Kruidvat", + "region": "nl", + "brandColor": "#E2001A", + "monogram": "Kv", + "hosts": [{ "value": "https://kruidvatnl-prod.mirakl.net", "label": "Netherlands" }], + "countries": ["NL"], + "shopIdNeeded": false, + "access": "Kruidvat selects its sellers and reviews each application, including service levels and the product selection. There is no setup or monthly fee, only a commission per sale that depends on the product type. Partner items are sold online only, and the seller ships every order.", + "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": ["Kruidvat seller API", "Kruidvat partner", "kruidvat.nl marketplace", "Kruidvat Mirakl", "A.S. Watson"], + "sources": [ + "https://support.channelengine.com/hc/en-us/articles/13085938631069-Kruidvat-marketplace-guide", + "https://e-tailize.com/help/marketplaces/sell-on-kruidvat/", + "https://e-tailize.com/integrations/selling-on-kruidvat/" + ] + }, + { + "slug": "flowers-1800", + "name": "1-800-Flowers.com Marketplace", + "retailer": "1-800-Flowers.com", + "region": "intl", + "brandColor": "#65388B", + "monogram": "18", + "hosts": [{ "value": "https://1800flowers-prod.mirakl.net", "label": "United States" }], + "countries": ["US"], + "shopIdNeeded": false, + "access": "1-800-Flowers.com approves each product for its marketplace assortment; apply with the Start Selling form on its sellers page. The commission is 25 % of the selling price plus shipping, and baby, children's and food products need extra insurance and compliance documents.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": "https://www.1800flowers.com/sellers", + "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": ["1800 Flowers", "1800flowers", "1-800-Flowers", "1-800-Flowers seller API", "1800Flowers Marketplace", "1-800-Flowers Mirakl"], + "sources": [ + "https://www.1800flowers.com/sellers", + "https://www.edesk.com/appstore/1800-flowers", + "https://flow.space/mirakl", + "https://base.com/en-IN/integrations/1800flowers/", + "https://www.channelengine.com/en/marketplaces/mirakl", + "https://www.retailtouchpoints.com/news/1-800-flowers-com-introduces-marketplace-to-expand-gift-options-support-independent-sellers/125786/" + ] + }, + { + "slug": "minted", + "name": "Minted Marketplace", + "retailer": "Minted", + "region": "intl", + "brandColor": "#1A1A1A", + "monogram": "Mi", + "hosts": [{ "value": "https://mintedus-prod.mirakl.net", "label": "United States" }], + "countries": ["US"], + "shopIdNeeded": false, + "access": "Minted is curated: makers send an interest form that its merchandising team reviews, then make and ship their own products. Makers keep 75 % of each sale and pay no listing fee.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": "https://www.minted.com/participate/overview", + "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": ["Minted seller API", "Minted maker marketplace", "Minted Direct From Artist", "Minted Mirakl"], + "sources": [ + "https://www.channelengine.com/en/marketplaces/mirakl", + "https://base.com/en-IN/integrations/mintedus/", + "https://www.minted.com/participate/overview", + "https://www.retaildive.com/news/minted-launches-wedding-marketplace/689537" + ] + }, + { + "slug": "parts-town", + "name": "Parts Town Marketplace", + "retailer": "Parts Town", + "region": "intl", + "brandColor": "#1A1A1A", + "monogram": "PT", + "hosts": [{ "value": "https://partstown-prod.mirakl.net", "label": "United States" }], + "countries": ["US"], + "shopIdNeeded": false, + "access": "Parts Town approves both the seller and each product; apply by e-mail (`marketplaceteam@partstown.com`). Sellers are suppliers and distributors of genuine OEM parts and other products for foodservice, HVAC, laundry and plumbing technicians; they set their own prices and shipping and ship the orders themselves. There is no sign-up or monthly fee, only a referral fee by category on each sale.", + "keyPath": "your user name (top right) > My user settings > API key", + "sellerHelpUrl": "https://www.partstown.com/marketplace-sellers", + "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": ["PartsTown", "Parts Town seller API", "Parts Town Marketplace sellers", "Parts Town Mirakl"], + "sources": [ + "https://www.partstown.com/marketplace-sellers", + "https://www.partstown.com/marketplace", + "https://www.mirakl.com/blogs/marketplace/airbus-helicopters-and-parts-town-share-how-theyre-delivering-a-better-b2b-digital-buying-experience/", + "https://base.com/en-IN/integrations/partstown/", + "https://www.channelengine.com/en/marketplaces/mirakl" + ] } ] } diff --git a/server.json b/server.json index efdb3f56b..b79b97cc8 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: 877 connectors (SAP, ERP, SQL), file search, memory and skills.", + "description": "MCP gateway and company brain: 886 connectors (SAP, ERP, SQL), file search, memory and skills.", "repository": { "url": "https://github.com/HelpCode-ai/anythingmcp", "source": "github"