登入開始免費試用
easyCoexistence 官方 API

自動將新 Nuvemshop 及 Tiendanube 商品發佈至 Instagram、TikTok 及 Facebook

Nuvemshop 或 Tiendanube 應用程式的 product/created webhook,可透過 easyCoexistence 將每個新商品發佈至 Instagram、TikTok 及 Facebook:n8n 或簡短程式碼會讀取商品、把主圖轉為 JPEG 供 Instagram 使用,再將文字、圖片與連結傳送至 easyCoexistence 的 posts API,後者透過各社交網絡的官方 API 發佈,可即時發佈,亦可稍後發佈。Claude 可按要求,透過 Nuvemshop 自家的連接器發佈商品。

3 seconds

Nuvemshop 在重試前等待 webhook 回傳 2XX 回應的時限,48 小時內最多嘗試 16 次。

store_id, event, id

Nuvemshop 商品 webhook 所帶的欄位包括時間戳記,但不含商品詳情,因此須以 GET /products/{id} 讀取商品。

x-linkedstore-hmac-sha256

承載每個 webhook 的 HMAC-SHA256 簽署的標頭,以應用程式的 client secret 作為金鑰,而非商店的存取權杖。

WebP

Nuvemshop 優化後可能提供的商品圖片格式,API 並無選項可關閉此轉換。

admin-mcp.nuvemshop.com.br

Nuvemshop 幫助中心列出的地址,用於把其自家 MCP 連接器以自訂連接器形式加入 Claude。

1080 × 1920

TikTok 相片貼文接受的最大圖片為 1920 × 1080,格式為 JPG 或 WebP,最大 20 MB。

新 Nuvemshop 商品如何變成貼文?

透過應用程式、webhook,以及每個帳戶一次呼叫。Nuvemshop 的 webhook 屬於某個應用程式,因此請建立一個具 read_products 範圍的應用程式,安裝到你的商店,並登記一個指向你的 n8n 工作流程或伺服器、事件為 product/created 的 webhook。通知包含商店 ID、事件及商品 ID,但不含商品詳情,因此工作流程需以 GET /products/{id} 讀取商品,確認商品可見且有相片,然後對每個帳戶向 easyCoexistence 的 posts API 發出一次請求:Instagram 與 TikTok 發相片貼文,Facebook 發連結貼文。easyCoexistence 會透過該網絡的官方 API 逐一發佈,可即時發佈,或於你設定的 publish_at 時間發佈。

1product/createdNuvemshop's webhook, signed
2GET /products/{id}Name, images, variants, canonical_url
3Checkvisibility visible, at least one image
4Posts APIOne call per account, now or later

如何設定 Nuvemshop 應用程式及其 webhook?

只需設定一次,過程透過 Partners Portal 及終端機完成。註冊成為 Nuvemshop 或 Tiendanube 合作夥伴,在 Apps 下建立具 read_products 的應用程式(該範圍亦涵蓋商品圖片及變體),並安裝到你的商店。發送到你的 redirect URL 的授權碼有效 5 分鐘,須於 https://www.tiendanube.com/apps/authorize/token 兌換為存取權杖及 user_id(即商店 ID)。該權杖在你為該應用程式及商店取得新權杖之前,或應用程式被解除安裝之前,都不會過期。之後以 POST /webhooks 登記 webhook。每個請求都須包含附有權杖的 Authorization: Bearer,以及一個 User-Agent,列明你的應用程式及聯絡方式,否則 Nuvemshop 會回傳 400。

Register the product/created webhook
curl -X POST "https://api.nuvemshop.com.br/2025-03/<STORE_ID>/webhooks" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "User-Agent: Product posts (you@example.com)" \
  -H "Content-Type: application/json" \
  -d '{ "event": "product/created", "url": "https://n8n.example.com/webhook/nuvemshop-products" }'

n8n 工作流程如何處理每個商品?

依次為回應、驗證、讀取、轉換及發佈。開啟 Raw Body 並將 Respond 設為 Immediately 的 Webhook 節點,會在 Nuvemshop 的 3 秒限時內作出回應。Extract From File 節點將請求內容轉為文字;Crypto 節點以 SHA256 及 HEX 計算其 Hmac,金鑰為應用程式的 client secret;If 節點則只在結果等於 x-linkedstore-hmac-sha256 標頭時才讓流程繼續。

之後,HTTP Request 節點使用商店的權杖讀取 GET /products/{{ $json.id }}。If 節點在 visibility 為 visible 且 images 不為空時繼續;Remove Duplicates 節點設為 Remove Items Processed in Previous Executions,會剔除已發佈的商品,因為 Nuvemshop 可能重複發送同一通知。針對 Instagram,HTTP Request 節點將主圖下載為檔案,Edit Image 節點以 jpeg 作為 Format 調整尺寸,然後 HTTP Request 節點把它以 n8n Binary File 形式傳送至 POST /api/v1/media,該端點會回傳 media_id。每個帳戶各使用一個 HTTP Request 節點,呼叫 POST /api/v1/channels/<account_id>/posts。

1WebhookRaw Body on, Respond Immediately
2Crypto and IfHMAC-SHA256 against the header
3HTTP RequestGET the product, then its main image
4Edit ImageResized, Format jpeg, sent to POST /media
5HTTP RequestPOST /channels/:id/posts per account

如何在不使用 n8n 的情況下以腳本發佈商品?

透過一個小型網頁端點。下面的 Python 以應用程式的 client secret 對原始請求內容檢查簽署,即時回傳 200,其餘工作則於背景進行:讀取商品、略過不可見或沒有相片的商品,並以 Pillow 將主圖轉為每邊最多 1080 像素的 JPEG,這格式 Instagram 與 TikTok 均接受。它把該檔案上傳至 POST /media,發佈到 Instagram 及 TikTok,並在 Facebook 發出連結貼文。每個呼叫都帶有由商品及帳戶組成的 Idempotency-Key,easyCoexistence 會予以遵從;另設一組已發佈 ID,防止重複通知造成重複發佈。

Python: post each new Nuvemshop product (pip install flask requests pillow)
import hashlib, hmac, io, os, threading
import requests
from flask import Flask, request
from PIL import Image

NS = f"https://api.nuvemshop.com.br/2025-03/{os.environ['NS_STORE_ID']}"
NS_HEADERS = {"Authorization": f"Bearer {os.environ['NS_ACCESS_TOKEN']}",
              "User-Agent": "Product posts (you@example.com)"}
EC = "https://easycoexistence.com/api/v1"
EC_AUTH = {"Authorization": f"Bearer {os.environ['EC_API_KEY']}"}  # ec_live_...
IG, TT, FB = os.environ["IG_ACCOUNT"], os.environ["TT_ACCOUNT"], os.environ["FB_ACCOUNT"]
LANG = os.environ.get("STORE_LANG", "pt")
posted, lock = set(), threading.Lock()  # a database in production
app = Flask(__name__)

@app.post("/nuvemshop/products")
def product_event():
    body = request.get_data()  # the raw body, before any parsing
    sig = hmac.new(os.environ["NS_CLIENT_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, request.headers.get("x-linkedstore-hmac-sha256", "")):
        return "", 401
    threading.Thread(target=post_product, args=(request.get_json()["id"],)).start()
    return "", 200  # inside Nuvemshop's 3 seconds

def jpeg_media_id(src):
    img = Image.open(io.BytesIO(requests.get(src, timeout=30).content)).convert("RGB")
    img.thumbnail((1080, 1080))
    out = io.BytesIO()
    img.save(out, "JPEG", quality=90)
    r = requests.post(f"{EC}/media", data=out.getvalue(), timeout=60,
                      headers={**EC_AUTH, "Content-Type": "image/jpeg"})
    r.raise_for_status()
    return r.json()["media_id"]

def post_product(product_id):
    p = requests.get(f"{NS}/products/{product_id}", headers=NS_HEADERS, timeout=30).json()
    if p.get("visibility") != "visible" or not p.get("images"):
        return
    with lock:
        if product_id in posted:
            return
        posted.add(product_id)
    name, url = p["name"].get(LANG, ""), p["canonical_url"]
    main = min(p["images"], key=lambda i: i["position"])["src"]
    media = [{"media_id": jpeg_media_id(main), "type": "image"}]
    for account, post in [
        (IG, {"text": f"New in the shop: {name}. {url}", "media": media}),
        (TT, {"text": f"New in the shop: {name}", "title": name[:90], "media": media}),
        (FB, {"text": f"New in the shop: {name}", "link": {"url": url}}),
    ]:
        requests.post(f"{EC}/channels/{account}/posts", json=post, timeout=60,
                      headers={**EC_AUTH, "Idempotency-Key": f"nuvemshop-{product_id}-{account}"})

Claude 與 ChatGPT 如何按要求發佈商品?

透過 Nuvemshop 自家的連接器,與 easyCoexistence 的連接器並用。Nuvemshop 幫助中心描述了一個建基於 MCP 的 AI 連接器,可與 Claude 配合使用,與 ChatGPT 則透過其連接器功能配合,亦可用於 Cursor 等編輯器;在 Claude 中,需以自訂連接器形式加入 https://admin-mcp.nuvemshop.com.br,其讀取工具可查詢商品、訂單及客戶。例如,你可以這樣提出要求:「明天上午 10 時(聖保羅時間)起,把我們最新的五件商品每小時一件發佈到 TikTok,每件附上文案。」助手會讀取商品、撰寫文案,並以 scheduled_at 安排每則貼文。它只在被要求時行動,不會於對話之間監察商店,因此夜間新增的商品會透過 webhook 發佈。

各網絡對商品貼文有何要求?

各網絡的規則,加上 easyCoexistence 自身的檢查,會在貼文發出或排程時套用,因此無法發出的商品會即時被拒絕:

  • Instagram:只接受 JPEG 圖片,因此須先把 WebP 或 PNG 商品相片轉換格式;多張相片會組成輪播。貼文沒有連結欄位,因此商品地址須以文字形式放入文案中。
  • TikTok:相片貼文可包含 1 至 35 張 JPG 或 WebP 圖片,每張最大 1080 × 1920 或 1920 × 1080 像素及 20 MB,標題 90 字元,每個帳戶每日最多 15 則相片貼文。
  • Facebook:連結貼文指向商品的 canonical_url,預覽由 Facebook 根據頁面的 Open Graph 標籤生成;或為一張相片,地址寫在文字中。
  • 透過 easyCoexistence 的媒體:HTTPS 連結,或來自 POST /media 的 media_id,圖片最大 30 MB,於排程貼文時複製。
  • 文案:Nuvemshop 的名稱及描述為以語言作鍵的物件,例如 pt 或 es,且描述為 HTML,因此須選定一種語言並去除標籤。

設定方法

  1. Connect the store's accountsIn the easyCoexistence dashboard, connect the Instagram account, TikTok account and Facebook Page, note each account_id, and create a Partner API key under Profile, Developers.
  2. Create the Nuvemshop appIn the Partners Portal, create an app with read_products, install it in the store, and keep its access token, client secret and the store ID.
  3. Register the webhookCall POST /webhooks with product/created and your n8n Production URL or server address, then add a test product and check the posts.

常見錯誤

  • 在貼文發出之後才回應 Nuvemshop。它會等待 3 秒以獲取 2XX 回應,之後重試,48 小時內最多 16 次,因此應先回應,之後才發佈。
  • 把 Nuvemshop 提供的商品相片直接送給 Instagram。Nuvemshop 可能無論網址結尾為何都回傳 WebP,而 Instagram 只接受 JPEG,因此應檢查檔案的 Content-Type 並轉換格式。
  • 以商店的存取權杖驗證簽署。Nuvemshop 以應用程式的 client secret 對原始請求內容簽署,因此應在請求內容被解析之前計算 HMAC。
  • 商品一經建立即發佈。商品可能以隱藏狀態或沒有相片的狀態開始,因此應檢查 visibility 與 images,也監聽 product/updated,並確保每件商品只發佈一次。
使用 EasyCoexistence 完成這項設定

easyCoexistence 讓你的商店,以及負責營運它的 AI 代理,能透過 Instagram、TikTok、Facebook 及更多渠道接觸客戶,每個渠道均透過其官方 API 運作:為 n8n 及你的腳本提供 posts API 與媒體上傳,為 Claude 與 ChatGPT 提供一個與 Nuvemshop 自家並用的 MCP 連接器,以及可提前 90 天發佈的佇列,且每個連接均獲 24/7 監察。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。

常見問題

支援 Tiendanube 商店嗎?

支援。Nuvemshop 與 Tiendanube 共用同一個 API:文件中每個 tiendanube.com 地址,在 nuvemshop.com.br 都有相同的對應地址,而 API 在 api.tiendanube.com 與 api.nuvemshop.com.br 兩個網域均可使用。

商品開始促銷時能否再次發佈?

可以。同時監聽 product/updated,並把變體的 promotional_price 與你上次發佈的價格作比較;通知只帶商品 ID,不含詳情,因此每次都須讀取商品。

Nuvemshop 自家的 Instagram 及 Facebook 渠道是做什麼的?

如 Nuvemshop 幫助中心所述,它把商店的目錄、Pixel 及商店連接到 Meta,以便在 Instagram 及 Facebook 銷售,可在後台的「Canais de venda」中設定。此流程則為每件新商品發佈一則動態貼文。

發佈 Nuvemshop 商品,easyCoexistence 收費多少?

每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,各網絡收費相同。posts API、媒體上傳及 MCP 連接器均包括在內,首 3 天免費。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期