Dla deweloperów i agentów

API i MCP do edycji Twojej witryny

Podłącz Claude, ChatGPT, Cursor lub własny skrypt do swojej witryny Mercader. Mogą czytać i edytować Twój profil, produkty, wydarzenia i linki, a każda zmiana jest widoczna od razu.

Utwórz token w panelu Przeczytaj przewodnik krok po kroku

Zacznij w minutę

Wybierz swojego klienta. Z OAuth nie kopiujesz żadnego tokenu: Twój asystent otwiera ekran uprawnień Mercader, a Ty zatwierdzasz dostęp.

Claude.ai lub ChatGPT

Dodaj własny konektor i wklej ten adres URL:

https://web.mercader.app/api/mcp/me

Claude Code

claude mcp add --transport http mercader https://web.mercader.app/api/mcp/me

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "mercader": {
      "url": "https://web.mercader.app/api/mcp/me"
    }
  }
}

curl lub własny kod

Utwórz token osobisty w panelu i wyślij go jako Bearer:

curl https://web.mercader.app/api/v1/me \
  -H "Authorization: Bearer mk_live_…"

Uwierzytelnianie

Każde żądanie zawiera nagłówek Authorization: Bearer <token>. Token daje dostęp tylko do witryny osoby, która go utworzyła.

OAuth 2.1 (zalecane dla asystentów)

Dynamiczna rejestracja klientów (RFC 7591) i kod autoryzacji z PKCE S256. Tylko klienci publiczni, bez sekretu.
Odkrywanie: odpowiedź 401 z MCP zawiera WWW-Authenticate z adresem URL metadanych chronionego zasobu.
Token dostępu jest ważny 1 godzinę, a token odświeżania 30 dni. Każde odświeżenie wymienia oba tokeny na nowe.
Unieważnianie (RFC 7009) pod /oauth/revoke albo w dowolnym momencie z panelu.

Tokeny osobiste

Tworzysz je w panelu, w Admin › Asystenci AI. Zaczynają się od mk_live_ i pokazują się tylko raz.
Nie wygasają: unieważnij je w panelu, kiedy przestaniesz ich używać.
Przydatne do skryptów, curl i klientów, które nie obsługują OAuth.

https://web.mercader.app/.well-known/oauth-protected-resource
https://web.mercader.app/.well-known/oauth-authorization-server

Uprawnienia (scopes)

Uprawnienia (scopes)
Uprawnienie	Co robi
`profile:write`	Nazwa, opis, kolor, język, waluta, logo, okładka i linki.
`catalog:write`	Produkty, wydarzenia i targi oraz ich zdjęcia.

REST API

JSON po HTTPS. Pola, których nie wyślesz, pozostają bez zmian; pusty ciąg znaków usuwa pole opcjonalne.

https://web.mercader.app/api/v1

REST API
Metoda	Ścieżka	Uprawnienie	Co robi
GET	`/me`	dowolny	Profil, plan i limity, produkty, wydarzenia i linki, wraz z ich id.
PATCH	`/profile`	`profile:write`	Zmienia nazwę, opis, kolor, język, kraj, walutę, logo lub okładkę.
GET	`/products`	dowolny	Zwraca listę produktów.
POST	`/products`	`catalog:write`	Tworzy produkt (name i price są wymagane).
PATCH	`/products/{id}`	`catalog:write`	Zmienia cenę, zdjęcie, dostępność lub inne pola.
DELETE	`/products/{id}`	`catalog:write`	Usuwa produkt.
GET	`/events`	dowolny	Zwraca listę wydarzeń i targów.
POST	`/events`	`catalog:write`	Tworzy wydarzenie (title i start_date w ISO 8601).
PATCH	`/events/{id}`	`catalog:write`	Zmienia wydarzenie.
DELETE	`/events/{id}`	`catalog:write`	Usuwa wydarzenie.
GET	`/social-links`	dowolny	Zwraca listę linków społecznościowych i kontaktowych.
POST	`/social-links`	`profile:write`	Dodaje link (Instagram, WhatsApp, Website, Email…).
PATCH	`/social-links/{id}`	`profile:write`	Zmienia link.
DELETE	`/social-links/{id}`	`profile:write`	Usuwa link.
POST	`/uploads`	zależnie od typu	Zwraca podpisany URL do wgrania zdjęcia.

Przykład: tworzenie produktu

curl -X POST https://web.mercader.app/api/v1/products \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Taza de gres", "price": 22, "description": "300 ml"}'

Pełne schematy w specyfikacji OpenAPI 3.1

Wgrywanie zdjęć

Poproś o wgranie, podając kind (product, event, avatar lub header) i content_type (image/jpeg, image/png lub image/webp).
Wyślij bajty zdjęcia metodą PUT na upload_url. URL wygasa po 2 godzinach.
Użyj public_url jako image_url produktu lub wydarzenia albo jako avatar_url lub header_url profilu.

Serwer MCP

Streamable HTTP, bezstanowy. Te same operacje, walidacja i limity co w REST API.

https://web.mercader.app/api/mcp/me

Serwer MCP
Narzędzie	Co robi
`get_my_storefront`	Aktualny stan witryny: profil, publiczny URL, plan, limity i wszystkie elementy z ich id.
`update_profile`	Zmienia tylko te pola profilu, które otrzyma. Adresu (slug) nie można zmienić.
`create_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_social_link`	Tworzy, zmienia lub usuwa produkty, wydarzenia i linki. Narzędzia usuwające są oznaczone jako destrukcyjne.
`create_image_upload`	Przygotowuje wgranie zdjęcia i zwraca upload_url oraz public_url.

Publiczny MCP tylko do odczytu

Aby przeszukiwać wszystkie opublikowane witryny, bez uwierzytelniania:

https://web.mercader.app/api/mcp

Limity i błędy

120 żądań na minutę i token. Po przekroczeniu 429 z Retry-After.
Limity Twojego planu działają tak samo jak w panelu: po osiągnięciu maksimum dostajesz 403 plan_limit.
Odpowiedzi zawierają Cache-Control: no-store.

Format błędu

Każdy błąd zwraca JSON ze stałym kodem i czytelnym opisem:

{
  "error": "plan_limit",
  "error_description": "…"
}

Format błędu
Kod	HTTP	Znaczenie
`invalid_input`	400	Brakuje pola, pole jest nieznane lub ma nieprawidłowy format.
`invalid_token`	401	Token jest nieobecny, nieznany, unieważniony lub wygasł.
`insufficient_scope`	403	Token nie ma uprawnienia wymaganego przez operację.
`plan_limit`	403	Osiągnięto limit planu albo okres próbny się skończył.
`not_found`	404	Element nie istnieje w Twojej witrynie.
`no_profile`	409	Konto nie ukończyło jeszcze onboardingu.
`rate_limited`	429	Zbyt wiele żądań w ostatniej minucie.

Bezpieczeństwo i prywatność

Przechowujemy tylko hash każdego tokenu. Jeśli go zgubisz, utwórz nowy.
Token nie daje dostępu do Twoich zapytań, opinii ani rozliczeń i nie pozwala zmienić adresu Twojej witryny.
Zmiany są od razu widoczne dla Twoich klientów: poproś asystenta, żeby potwierdził przed usunięciem.

Nie masz jeszcze witryny?

Załóż swoją i podłącz asystenta później. Mercader daje 14 dni próbnych.

Załóż moją witrynę