Nostrus B2B
Nostrus Product API · v1

API produktów

Interfejs tylko do odczytu, przeznaczony do pobierania katalogu produktów DROP: nazw, kodów EAN i SKU, cen brutto, stanów magazynowych, opisów, parametrów oraz zdjęć.

HTTPS + JSONTylko odczytAktualizacja danych co 15 minutOpenAPI 3.1
https://nostrus.pl/products_api.php

Szybki start

  1. Zaloguj się do panelu Nostrus B2B i przejdź do zakładki „Integracje”.
  2. Wybierz „Użyj API”, nadaj nazwę integracji i wygeneruj klucz.
  3. Skopiuj klucz od razu — pełna wartość jest wyświetlana tylko jeden raz.
  4. Wywołuj API wyłącznie z backendu swojego sklepu lub serwera.
curl -H "X-Nostrus-Token: TWOJ_KLUCZ" \
  "https://nostrus.pl/products_api.php?page=1&limit=50"
Poprawna odpowiedź ma kod HTTP 200, pole success: true, tablicę data oraz obiekt meta z informacjami o paginacji i czasie przygotowania danych.

Uwierzytelnianie

Każde zapytanie musi zawierać aktywny klucz API. Zalecany jest nagłówek X-Nostrus-Token:

X-Nostrus-Token: TWOJ_KLUCZ

Alternatywnie można użyć standardowego schematu Bearer:

Authorization: Bearer TWOJ_KLUCZ
Bezpieczeństwo: nie umieszczaj klucza w adresie URL, publicznym repozytorium ani kodzie JavaScript uruchamianym w przeglądarce. Klucz powinien znajdować się w konfiguracji backendu lub magazynie sekretów.

Usunięcie klucza w panelu unieważnia go natychmiast. Kolejne wywołania zwrócą HTTP 401.

Dostępne operacje

API używa jednego endpointu i metody GET. Rodzaj operacji wynika z przekazanych parametrów.

OperacjaZapytanieOpis
Lista produktówGET ?page=1&limit=50Zwraca stronę produktów oraz dane paginacji.
Produkt po IDGET ?id=123Zwraca pojedynczy produkt o wskazanym identyfikatorze.
Produkt po EANGET ?ean=5901234567890Zwraca pojedynczy produkt o dokładnie pasującym kodzie EAN.

Parametry listy

ParametrTypWymaganyDomyślnieOpis
pageintegerNie1Numer strony, zaczynając od 1.
limitintegerNie50Liczba produktów: od 1 do 100.
idintegerNie—Dodatni identyfikator produktu. Używaj bez parametru ean.
eanstringNie—Pełny kod EAN. Używaj bez parametru id.

Paginacja

Lista zwraca maksymalnie 100 produktów w jednej odpowiedzi. Odczytuj kolejne strony, aż wartość meta.page będzie równa meta.pages.

GET /products_api.php?page=1&limit=100
GET /products_api.php?page=2&limit=100

meta.page   = bieżąca strona
meta.limit  = rozmiar strony
meta.total  = liczba wszystkich produktów
meta.pages  = liczba wszystkich stron
Nie zakładaj stałej liczby produktów ani stron. Katalog może się zmieniać, dlatego przy każdej pełnej synchronizacji korzystaj z aktualnego obiektu meta.

Model produktu

PoleTypZnaczenie
idintegerStały identyfikator produktu w katalogu Nostrus. Zalecany klucz główny integracji.
namestringNazwa produktu.
eanstringKod EAN. Zachowuj jako tekst, aby nie utracić zer wiodących.
skustringSymbol magazynowy produktu.
pricenumber | nullCena brutto z grupy cenowej przypisanej do właściciela tokena. null oznacza brak ceny w tej grupie.
currencystringKod waluty ustawionej dla właściciela tokena, np. PLN, EUR lub CZK.
stockintegerAktualna dostępna ilość. Minimalna wartość to 0.
availablebooleantrue, gdy stock > 0.
producerstringNazwa producenta lub właściciela katalogu.
categorystringKategoria produktowa.
weight_kgnumber | string | nullWaga produktu w kilogramach, jeżeli jest dostępna.
dimensions_cmobjectObiekt z polami length, width i height w centymetrach.
description_htmlstringOpis w HTML. Przed wyświetleniem w niezaufanym środowisku zastosuj bezpieczne filtrowanie HTML.
imagesarray<string>Lista bezpośrednich adresów zdjęć w kolejności katalogowej.
updated_atstring (ISO 8601)Czas przygotowania wersji danych produktu.

Format odpowiedzi

Lista produktów

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Nazwa produktu",
      "ean": "5901234567890",
      "sku": "SKU-123",
      "price": 199.00,
      "currency": "PLN",
      "stock": 25,
      "available": true,
      "producer": "Nostrus",
      "category": "fotele gamingowe",
      "weight_kg": 16,
      "dimensions_cm": {"length": 25, "width": 59, "height": 77},
      "description_html": "<p>Opis produktu</p>",
      "images": ["https://example.com/image.jpg"],
      "updated_at": "2026-10-08T18:00:02+02:00"
    }
  ],
  "meta": {
    "version": "v1",
    "generated_at": "2026-10-08T18:00:02+02:00",
    "generated_at_ts": 1791475202,
    "product_count": 116,
    "currency": "PLN",
    "price_group_id": 11337,
    "page": 1,
    "limit": 50,
    "total": 116,
    "pages": 3
  }
}

Pojedynczy produkt

Przy wyszukiwaniu po id lub ean pole data zawiera jeden obiekt produktu, a nie tablicę.

{
  "success": true,
  "data": { "id": 123, "name": "Nazwa produktu", "stock": 25 },
  "meta": { "version": "v1", "generated_at": "..." }
}

ETag i oszczędzanie transferu

Każda poprawna odpowiedź zawiera nagłówek ETag. Zapisz jego wartość i przy kolejnym pobraniu wyślij ją w nagłówku If-None-Match.

curl -i \
  -H "X-Nostrus-Token: TWOJ_KLUCZ" \
  -H 'If-None-Match: "ZAPISANY_ETAG"' \
  "https://nostrus.pl/products_api.php?page=1&limit=100"

Jeżeli dana strona się nie zmieniła, API zwróci HTTP 304 bez treści. Wtedy zachowaj dane zapisane lokalnie. Odpowiedź 304 nadal liczy się jako wywołanie API.

Limity i nagłówki

30 zapytań/minutę

Limit przypisany do pojedynczego klucza API.

2000 zapytań/dobę

Dobowy limit pojedynczego klucza.

120 zapytań/minutę/IP

Ochrona przed nadmierną liczbą prób z jednego adresu.

100 produktów/stronę

Maksymalna wartość parametru limit.

API zwraca nagłówki:

  • X-RateLimit-Limit — limit minutowy.
  • X-RateLimit-Remaining — pozostałe wywołania w bieżącej minucie.
  • X-DailyLimit-Remaining — pozostałe wywołania w bieżącej dobie.
  • Retry-After — czas oczekiwania po odpowiedzi 429.

Błędy i kody HTTP

HTTPKod błęduZnaczenie i działanie
200—Zapytanie zakończone prawidłowo.
304—Dane nie zmieniły się. Użyj lokalnie zapisanej odpowiedzi.
400invalid_limit / invalid_pagePopraw parametry zapytania.
401invalid_tokenBrak klucza, nieprawidłowy klucz, klucz usunięty albo konto nieaktywne.
404product_not_foundProdukt o podanym ID lub EAN nie występuje w aktualnym katalogu.
405method_not_allowedUżyj metody GET.
429rate_limit_exceeded / ip_rate_limit_exceededWstrzymaj zapytania zgodnie z nagłówkiem Retry-After.
503catalog_unavailable / service_unavailableZachowaj poprzednie dane i ponów próbę później z narastającym opóźnieniem.
{
  "success": false,
  "error": {
    "code": "invalid_token",
    "message": "Brak prawidłowego lub aktywnego tokena API."
  }
}

Przykłady integracji

PHP 8 — cURL

<?php
$token = getenv('NOSTRUS_API_TOKEN');
$url = 'https://nostrus.pl/products_api.php?page=1&limit=100';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ['X-Nostrus-Token: ' . $token],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException('Nostrus API HTTP ' . $status);
}
$response = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
foreach ($response['data'] as $product) {
    echo $product['id'] . ' ' . $product['stock'] . PHP_EOL;
}

Python — requests

import os
import requests

response = requests.get(
    "https://nostrus.pl/products_api.php",
    params={"page": 1, "limit": 100},
    headers={"X-Nostrus-Token": os.environ["NOSTRUS_API_TOKEN"]},
    timeout=20,
)
response.raise_for_status()
for product in response.json()["data"]:
    print(product["id"], product["stock"])

Node.js — fetch po stronie serwera

const url = new URL("https://nostrus.pl/products_api.php");
url.searchParams.set("page", "1");
url.searchParams.set("limit", "100");

const response = await fetch(url, {
  headers: { "X-Nostrus-Token": process.env.NOSTRUS_API_TOKEN }
});
if (!response.ok) throw new Error(`Nostrus API HTTP ${response.status}`);
const payload = await response.json();

Zalecany sposób synchronizacji

  1. Uruchamiaj synchronizację nie częściej niż co 15 minut.
  2. Pobieraj kolejne strony po 100 produktów i zapisuj je tymczasowo.
  3. Używaj pola id jako stabilnego identyfikatora, a EAN przechowuj jako tekst.
  4. Po pobraniu wszystkich stron aktualizuj ceny, stany, opisy i zdjęcia w jednej kontrolowanej operacji.
  5. Produkt nieobecny w zakończonej pełnej synchronizacji oznacz jako niedostępny dopiero po potwierdzeniu, że wszystkie strony zostały pobrane poprawnie.
  6. Przy błędzie zachowaj poprzedni poprawny katalog. Dla 429 i 503 zastosuj ponowienie z narastającym opóźnieniem.
Nie traktuj pola updated_at jako osobnego czasu zmiany każdego produktu. Informuje ono o czasie przygotowania aktualnego snapshotu katalogu.

Przekazanie integracji programiście lub AI

Do przygotowania integracji wystarczą trzy elementy:

  1. adres tej dokumentacji: https://nostrus.pl/api-docs.php,
  2. specyfikacja OpenAPI: https://nostrus.pl/openapi.php,
  3. klucz API przekazany bezpiecznym kanałem — nigdy w publicznym poleceniu lub repozytorium.

Przykładowe polecenie dla narzędzia AI

Zintegruj mój backend z Nostrus Product API v1 na podstawie:
https://nostrus.pl/api-docs.php
https://nostrus.pl/openapi.php

Token pobieraj ze zmiennej środowiskowej NOSTRUS_API_TOKEN.
Nie umieszczaj tokena w frontendzie ani w adresie URL.
Obsłuż paginację, ETag, HTTP 429/503 i zachowanie ostatnich poprawnych danych.

Rozwiązywanie problemów

ObjawNajczęstsza przyczynaRozwiązanie
HTTP 401Brak nagłówka, literówka, usunięty klucz lub nieaktywne konto.Wygeneruj aktywny klucz i sprawdź dokładną nazwę nagłówka.
HTTP 429Zbyt częste wywołania.Odczytaj Retry-After, ogranicz częstotliwość i użyj ETag.
HTTP 503Cache katalogu jest chwilowo niedostępny.Zachowaj poprzednie dane i ponów później.
Pusta kolejna stronaZmieniła się liczba produktów albo użyto nieaktualnej liczby stron.Zacznij nową pełną synchronizację od strony 1.
Opis zawiera znacznikiPole description_html jest kodem HTML.Wyświetl je bezpiecznie jako HTML albo usuń znaczniki po swojej stronie.
Przeglądarka blokuje wywołanieAPI jest przeznaczone do połączeń serwer–serwer.Przenieś zapytanie do backendu, co dodatkowo chroni klucz.