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://nostrus.pl/products_api.phpSzybki start
- Zaloguj się do panelu Nostrus B2B i przejdź do zakładki „Integracje”.
- Wybierz „Użyj API”, nadaj nazwę integracji i wygeneruj klucz.
- Skopiuj klucz od razu — pełna wartość jest wyświetlana tylko jeden raz.
- 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"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_KLUCZAlternatywnie można użyć standardowego schematu Bearer:
Authorization: Bearer TWOJ_KLUCZUsunię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.
| Operacja | Zapytanie | Opis |
|---|---|---|
Lista produktów | GET ?page=1&limit=50 | Zwraca stronę produktów oraz dane paginacji. |
Produkt po ID | GET ?id=123 | Zwraca pojedynczy produkt o wskazanym identyfikatorze. |
Produkt po EAN | GET ?ean=5901234567890 | Zwraca pojedynczy produkt o dokładnie pasującym kodzie EAN. |
Parametry listy
| Parametr | Typ | Wymagany | Domyślnie | Opis |
|---|---|---|---|---|
page | integer | Nie | 1 | Numer strony, zaczynając od 1. |
limit | integer | Nie | 50 | Liczba produktów: od 1 do 100. |
id | integer | Nie | — | Dodatni identyfikator produktu. Używaj bez parametru ean. |
ean | string | Nie | — | 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 stronmeta.Model produktu
| Pole | Typ | Znaczenie |
|---|---|---|
id | integer | Stały identyfikator produktu w katalogu Nostrus. Zalecany klucz główny integracji. |
name | string | Nazwa produktu. |
ean | string | Kod EAN. Zachowuj jako tekst, aby nie utracić zer wiodących. |
sku | string | Symbol magazynowy produktu. |
price | number | null | Cena brutto z grupy cenowej przypisanej do właściciela tokena. null oznacza brak ceny w tej grupie. |
currency | string | Kod waluty ustawionej dla właściciela tokena, np. PLN, EUR lub CZK. |
stock | integer | Aktualna dostępna ilość. Minimalna wartość to 0. |
available | boolean | true, gdy stock > 0. |
producer | string | Nazwa producenta lub właściciela katalogu. |
category | string | Kategoria produktowa. |
weight_kg | number | string | null | Waga produktu w kilogramach, jeżeli jest dostępna. |
dimensions_cm | object | Obiekt z polami length, width i height w centymetrach. |
description_html | string | Opis w HTML. Przed wyświetleniem w niezaufanym środowisku zastosuj bezpieczne filtrowanie HTML. |
images | array<string> | Lista bezpośrednich adresów zdjęć w kolejności katalogowej. |
updated_at | string (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
Limit przypisany do pojedynczego klucza API.
Dobowy limit pojedynczego klucza.
Ochrona przed nadmierną liczbą prób z jednego adresu.
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
| HTTP | Kod błędu | Znaczenie i działanie |
|---|---|---|
| 200 | — | Zapytanie zakończone prawidłowo. |
| 304 | — | Dane nie zmieniły się. Użyj lokalnie zapisanej odpowiedzi. |
| 400 | invalid_limit / invalid_page | Popraw parametry zapytania. |
| 401 | invalid_token | Brak klucza, nieprawidłowy klucz, klucz usunięty albo konto nieaktywne. |
| 404 | product_not_found | Produkt o podanym ID lub EAN nie występuje w aktualnym katalogu. |
| 405 | method_not_allowed | Użyj metody GET. |
| 429 | rate_limit_exceeded / ip_rate_limit_exceeded | Wstrzymaj zapytania zgodnie z nagłówkiem Retry-After. |
| 503 | catalog_unavailable / service_unavailable | Zachowaj 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
- Uruchamiaj synchronizację nie częściej niż co 15 minut.
- Pobieraj kolejne strony po 100 produktów i zapisuj je tymczasowo.
- Używaj pola
idjako stabilnego identyfikatora, a EAN przechowuj jako tekst. - Po pobraniu wszystkich stron aktualizuj ceny, stany, opisy i zdjęcia w jednej kontrolowanej operacji.
- Produkt nieobecny w zakończonej pełnej synchronizacji oznacz jako niedostępny dopiero po potwierdzeniu, że wszystkie strony zostały pobrane poprawnie.
- Przy błędzie zachowaj poprzedni poprawny katalog. Dla 429 i 503 zastosuj ponowienie z narastającym opóźnieniem.
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:
- adres tej dokumentacji:
https://nostrus.pl/api-docs.php, - specyfikacja OpenAPI:
https://nostrus.pl/openapi.php, - 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
| Objaw | Najczęstsza przyczyna | Rozwiązanie |
|---|---|---|
| HTTP 401 | Brak nagłówka, literówka, usunięty klucz lub nieaktywne konto. | Wygeneruj aktywny klucz i sprawdź dokładną nazwę nagłówka. |
| HTTP 429 | Zbyt częste wywołania. | Odczytaj Retry-After, ogranicz częstotliwość i użyj ETag. |
| HTTP 503 | Cache katalogu jest chwilowo niedostępny. | Zachowaj poprzednie dane i ponów później. |
| Pusta kolejna strona | Zmieniła się liczba produktów albo użyto nieaktualnej liczby stron. | Zacznij nową pełną synchronizację od strony 1. |
| Opis zawiera znaczniki | Pole description_html jest kodem HTML. | Wyświetl je bezpiecznie jako HTML albo usuń znaczniki po swojej stronie. |
| Przeglądarka blokuje wywołanie | API jest przeznaczone do połączeń serwer–serwer. | Przenieś zapytanie do backendu, co dodatkowo chroni klucz. |