API dla developerów

API Pricelists.org pozwala wyszukiwać oferty produktów na całym świecie, porównywać ceny, pobierać wyceny i realizować zakupy programistycznie — także dla agentów AI (np. Claude Code z OpenClaw).

Szybki start — wyszukiwanie ofert

Wyszukuj produkty i oferty w bazie 31 mln cen. Wyniki zawierają cenę, koszt dostawy, dostępność i czas ostatniej aktualizacji.

Przykładowe zapytanie

GET https://api.pricelists.org/v2/search
  ?query=Samsung+Galaxy+S25+Ultra
  &country=PL
  &limit=10

Przykładowa odpowiedź

{
  "query": "Samsung Galaxy S25 Ultra",
  "count": 8,
  "offers": [
    {
      "shop": "Media Expert",
      "price": 5199.00,
      "delivery": 0.00,
      "currency": "PLN",
      "available": true,
      "updated_at": "2026-07-22T09:41:00Z"
    }
  ]
}

Darmowy plan: 1 000 zapytań / miesiąc. Autoryzacja przez nagłówek X-Api-Key .

Przegląd

Agentowe API obejmuje pełen cykl handlowy przez siedem endpointów. Kontrakt maszynowy jest dostępny jako OpenAPI 3.1, ze skróconymi referencjami w llms.txt i llms-full.txt.

Autoryzacja

API korzysta z trójpoziomowego modelu dostępu:

• Publiczne (bez auth): /search i /register — wyszukiwanie i rejestracja bez tokenu.
• Uwierzytelnione (Bearer): /quote, /execute, /orders — wymagają tokenu Bearer w nagłówku Authorization .

Authorization: Bearer plk_your_api_key_here

Rejestracja

Agenci mogą samodzielnie uzyskać klucz API natychmiast — bez zatwierdzania.

POST /api/agent/v1/register

// Request
{
  "name": "MyBot v1.0"
}

// Response (201 Created)
{
  "apiKey": "plk_a1b2c3d4e5f6...",
  "keyPrefix": "plk_a1b2",
  "name": "MyBot v1.0",
  "rateLimit": 60,
  "message": "Store this API key securely. It will not be shown again."
}

Endpointy API

POST /api/agent/v1/search

Wyszukiwanie ofert po zapytaniu tekstowym lub identyfikatorach produktu.

{
  "query": "iPhone 15 Pro 256GB",
  "identifiers": { "gtin": ["194253938996"], "ean": [], "mpn": [] },
  "limit": 10,
  "currency": "USD",
  "locale": "en-US",
  "shipTo": { "country": "PL", "postalCode": "00-001" },
  "rankings": ["cheapest", "best"],
  "bestWeights": { "sellerCredibility": 0.80, "price": 0.15, "deliverySpeed": 0.05 },
  "filters": { "availability": "in_stock_only" }
}

POST /api/agent/v1/quote

Utwórz wycenę z limitem czasu, aby zablokować cenę przed realizacją.

// Request
{ "offerId": "of_12345", "quantity": 1, "currency": "USD",
  "shipTo": { "country": "PL", "postalCode": "00-001" } }

// Response
{
  "quoteId": "qt_abc-def-123",
  "expiresAt": "2026-02-10T12:15:00+00:00",
  "final": { "currency": "USD", "items": 999.99, "shipping": 0.0, "grandTotal": 999.99 },
  "execution": { "supported": false, "mode": "checkout_url",
    "fallbackCheckoutUrl": "https://techstore.pl/product/123" }
}

POST /api/agent/v1/execute

Realizacja zakupu. Wymaga nagłówka Idempotency-Key oraz confirm: true.

// Headers
Authorization: Bearer plk_...
Idempotency-Key: unique-request-id-123

// Request
{ "quoteId": "qt_abc-def-123", "confirm": true, "preference": "api_first" }

// Response (when merchant API is not supported)
{ "ok": false, "status": "not_supported", "orderId": "ord_xyz-789",
  "fallback": { "type": "checkout_url", "url": "https://techstore.pl/product/123" } }

GET /api/agent/v1/orders/{orderId}

Sprawdzanie statusu zamówienia po realizacji.

{
  "orderId": "ord_xyz-789",
  "status": "not_supported",
  "executionMode": "manual",
  "checkoutUrl": "https://techstore.pl/product/123",
  "receipt": { "currency": "USD", "total": 999.99 }
}

Tryby rankingu

Zgłoszenia (firma + oferty)

Agenci mogą zgłaszać nowe firmy i ich oferty do bazy Pricelists. Zgłoszenia przechodzą moderację, zanim produkty staną się wyszukiwalne.

POST /api/agent/v1/submit

{
  "company_name": "TechStore Poland",
  "company_website": "https://techstore.pl",
  "items": [
    { "title": "iPhone 15 Pro 256GB", "gtin": "194253938996", "brand": "Apple",
      "price": 4999.00, "currency": "PLN", "in_stock": true, "condition": "new",
      "link": "https://techstore.pl/iphone-15-pro" }
  ]
}

// Response (201 Created)
{ "submissionId": 42, "status": "submitted", "itemCount": 1 }

GET /api/agent/v1/submissions/{id}

Sprawdzanie statusu zgłoszenia (tylko właściciel klucza).

Instalacja skilla OpenClaw

Aby użyć API z agentem zgodnym z OpenClaw:

openclaw plugins install -l /path/to/pricelists-commerce-openclaw

Ustaw klucz w zmiennej PRICELISTS_AGENT_API_KEY i dodaj konfigurację wtyczki do ~/.openclaw/openclaw.json. Skill udostępnia sześć narzędzi: plc_search, plc_quote, plc_execute, plc_order_get, plc_submit, plc_submission_status.

Kody błędów

Publiczne API katalogu (bez klucza)

Obok API handlowego udostępniamy publiczne API katalogu do wyszukiwania, porównań i historii cen. Bez autoryzacji, odpowiedzi cache’owane przez ETag, tylko oferty potwierdzone przez sprzedawców. 60 zapytań/min na IP.

Model bezpieczeństwa

• API nigdy nie prosi o numery kart, CVV ani kody OTP.
• Realizacja zakupu jest API-first; gdy sklep nie wspiera API, agent otrzymuje checkout_url.
• /execute wymaga confirm: true oraz nagłówka Idempotency-Key.
• Wszystkie klucze API są hashowane (SHA-256).