Dokumentacja techniczna dla deweloperów. Połącz BaseLinker, WooCommerce, Apilo lub własne rozwiązanie WMS/ERP bezpośrednio z Marketplace Scopio. Zapewnij bezobsługowe pobieranie zamówień i natychmiastową synchronizację statusów dostawy oraz numerów śledzenia przesyłek.
Klucze API Sprzedawcy
Każde zapytanie do API Scopio musi być autoryzowane za pomocą unikalnego tokenu sprzedawcy. Token ten generowany jest w panelu administracyjnym. Używaj nagłówka Authorization z przedrostkiem Bearer lub bezpośrednio dedykowanego nagłówka X-API-Key.
Tokeny posiadają uprawnienia powiązane z Twoim kontem i profilem sprzedawcy. Przechowuj je w bezpiecznym miejscu (np. w zmiennych środowiskowych) i nigdy nie ujawniaj ich w kodzie klienckim. API obsługuje wyłącznie połączenia szyfrowane protokołem TLS 1.3.
# Authorization Header
Authorization: Bearer sk_mkt_ca1d5b9...
X-API-Key: sk_mkt_ca1d5b9...
Endpoint: GET /api/seller/orders
Endpoint umożliwia automatyczne pobieranie nowo opłaconych zamówień. Zwraca wyłącznie pozycje (składniki zamówienia), które należą do Twojej oferty sprzedawcy (filtrowanie po sellerId). Dane adresowe klienta oraz preferowana metoda dostawy (np. Paczkomaty InPost) są przekazywane w ustandaryzowanym formacie JSON.
Zalecany interwał odpytywania (polling interval) wynosi od 5 do 15 minut. Odpowiedź zawiera strukturę shipping_address z pełnymi danymi teleadresowymi kupującego, listą zamówionych produktów zawierających kody EAN, ilości oraz ceny sprzedaży netto i brutto.
# Response excerpt
{ "success": true, "orders": [...] }
Endpoint: POST /api/seller/orders/{orderId}/fulfill
Po spakowaniu paczki i wygenerowaniu etykiety przewozowej w swoim systemie (np. BaseLinker), prześlij status realizacji z powrotem do Scopio. Podaj numer śledzenia (tracking_number) oraz identyfikator przewoźnika (carrier), a system natychmiast zaktualizuje zamówienie i prześle powiadomienie do klienta końcowego.
Dozwolone identyfikatory przewoźników to m.in. inpost_locker (Paczkomaty), inpost_courier, dpd, dhl, ups. Możesz również opcjonalnie przesłać bezpośredni link do pobrania etykiety w formacie PDF (label_url), co umożliwi jej pobranie i podgląd bezpośrednio w panelu Scopio.
# Payload data
{ "tracking_number": "XYZ123", "carrier": "inpost_locker" }
Natychmiastowe zdarzenia HTTP POST
Skonfiguruj adres Webhook URL w swoim profilu sprzedawcy, aby otrzymywać powiadomienia w czasie rzeczywistym. System wyśle żądanie POST pod wskazany adres natychmiast po zaksięgowaniu płatności za zamówienie. Zapobiega to potrzebie ciągłego odpytywania API.
Każde powiadomienie webhook zawiera nagłówek signature generowany za pomocą klucza współdzielonego (Webhook Secret). Służy to do weryfikacji autentyczności nadawcy. W przypadku braku odpowiedzi ze statusem 200, system ponowi próbę wysłania powiadomienia 3-krotnie w odstępach 5-minutowych.
Gotowość na gospodarkę agentów AI
Struktury danych zamówień i statusów są w pełni zgodne ze standardem Universal Commerce Protocol (UCP). Pozwala to na automatyczne parsowanie danych przez autonomiczne boty wyszukiwania i zakupów oraz bezpośrednie indeksowanie ofert w ekosystemie Google i Gemini.
Dzięki mapowaniu danych zgodnie z formatem UCP, zamówienia składane przez autonomiczne systemy zakupowe są bez problemu przekazywane do Twojego systemu CRM bez konieczności tworzenia dedykowanych parserów dla każdego bota.
Bezpieczeństwo i wydajność infrastruktury
Standardowy limit zapytań do API wynosi 120 żądań na minutę na jeden adres IP / klucz API. Przekroczenie limitu skutkuje zwróceniem kodu HTTP 429 (Too Many Requests). Wszystkie błędy zwracane są w ustandaryzowanym formacie JSON zawierającym kod błędu i opis tekstowy.
API zwraca standardowe kody odpowiedzi HTTP: 400 (błędny payload), 401 (brak autoryzacji), 403 (brak dostępu do danego zamówienia), 404 (zamówienie nie istnieje), 500 (błąd wewnętrzny serwera). Wszystkie te zdarzenia są zapisywane w tabeli seller_crm_logs w celu diagnostyki.
# HTTP 429 Rate Limit Response
{ "error": "Too Many Requests", "retry_after_seconds": 60 }
