---
title: "API i MCP Mercader dla agentów AI"
description: "Dokumentacja REST API i serwera MCP Mercader: OAuth 2.1, tokeny osobiste, endpointy, narzędzia, wgrywanie zdjęć, limity i błędy."
url: https://www.mercader.app/pl/developers
language: pl
---

# 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: https://app.mercader.app/admin?tab=agents
- Przeczytaj przewodnik krok po kroku: https://www.mercader.app/pl/blog/zarzadzaj-witryna-z-ai.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## 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

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

### Cursor (~/.cursor/mcp.json)

```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:

```bash
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.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### 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.

### 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.

Base URL: `https://web.mercader.app/api/v1`

| 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

```bash
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](https://web.mercader.app/api/v1/openapi.json)

## Wgrywanie zdjęć

1. Poproś o wgranie, podając kind (product, event, avatar lub header) i content_type (image/jpeg, image/png lub image/webp).
2. Wyślij bajty zdjęcia metodą PUT na upload_url. URL wygasa po 2 godzinach.
3. 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
```

| 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_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_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:

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

| 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ę](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)