Jak używać — API — commonspecs

Zainstaluj w swoim agencie skill i dodaj zalecane połączenie MCP.
Zakładka API opisuje surowe endpointy.

Bazowy adres URL https://api.commonspecs.com.

Uwierzytelnianie

Wyślij bearer token w nagłówku:

Authorization: Bearer cs_live_…

POST /v1/get_product

Rozpoznaj produkt lub usługę po dokładnie jednym kluczu: id, url albo ean.

curl -X POST https://api.commonspecs.com/v1/get_product \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ean":"<EAN/GTIN>"}'

POST /v1/search_products

query szuka po nazwie marki, pozycji bądź kategorii — tak samo produktów, jak usług. category przegląda jedną kategorię po jej identyfikatorze. Identyfikatory kategorii zwracamy w polu matched_categories (trafienie) albo did_you_mean (pudło). filters zawężają wyniki po cechach zapisanych w specyfikacji i wymagają podania category. Dziesięć wyników na stronę. Po kolejne sięgasz parametrem page.

curl -X POST https://api.commonspecs.com/v1/search_products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"<brand or product name>","category":"<identifier from matched_categories>"}'

POST /v1/compare_products

Porównaj do pięciu pozycji jednocześnie. W polu product_ids podajesz id, które niesie każdy wynik wyszukiwania i odczytu — najpierw rozpoznaj każdą pozycję za pomocą search_products albo get_product, a potem przekaż otrzymane identyfikatory. To, czego jeszcze nie ma w bazie, nie ma identyfikatora — najpierw je zgłoś.

curl -X POST https://api.commonspecs.com/v1/compare_products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_ids":["…","…"]}'

POST /v1/submit_contribution

Zgłoś sprawdzone dane specyfikacji (fields) lub zaobserwowaną cenę wraz z datą (offer) — albo jedno i drugie. Wskaż produkt lub usługę tak samo jak przy odczycie. Podanie pary brand i name zakłada w bazie nowy wpis, jeśli takiej pozycji jeszcze nie ma. Gdy odczytujesz dane ze strony, dołącz do każdego pola source_url i dosłowny fragment źródła (snippet). Gdy odczytujesz je z samego produktu — z etykiety albo opakowania — przekaż "source": "label" i pomiń oba te pola.

curl -X POST https://api.commonspecs.com/v1/submit_contribution \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "brand":"<brand>","name":"<product name>","source":"web",
    "fields":[{"field_name":"<schema field>","value":"<value as printed>",
      "source_url":"https://…","snippet":"<verbatim text>"}],
    "offer":{"store":"<shop domain>","country":"<ISO 3166-1>","price":<number>,
      "currency":"<ISO 4217>","availability":"in_stock","source_url":"https://…"}
  }'

POST /v1/flag_stale

Zgłoś fakt lub cenę, które wyglądają na nieaktualne, błędne lub sporne. Zgłoszenie trafia do przeglądu i samo w sobie niczego w produkcie nie zmienia. field_name i reason są opcjonalne.