Przejdź do treści głównej

Deweloperzy

API Handlowe

REST-owe API tylko do odczytu dla Twojego sklepu VeeBoost: jeden opublikowany kontrakt, uwierzytelnianie kluczem i przewidywalna paginacja — zbudowane dla integracji, które pozostają zsynchronizowane.

Jeden kontrakt, opublikowany jako jedyne źródło prawdy

Twój sklep publikuje kompletny, maszynowo czytelny kontrakt (OpenAPI 3.1): każdy endpoint, parametr, odpowiedź i kod błędu API handlowego. Ta strona odsyła do niego i nigdy nie powtarza tabel endpointów — kontrakt nie może rozjechać się z rzeczywistością, a Twoja integracja również nie.

Opublikowany kontraktGET /openapi/v1.json

Szybki start

Trzy kroki do pierwszego odczytu katalogu:

  1. Utwórz klucz API w panelu administracyjnym (sekcja Deweloperzy) z potrzebnymi Ci zakresami odczytu. Zaczyna się od vbk_ i jest wyświetlany tylko raz.
  2. Przesyłaj go w nagłówku X-Api-Key przy każdym żądaniu — Twoja dzierżawa jest rozpoznawana z klucza, nigdy z hosta.
  3. Wywołaj swój pierwszy endpoint, na przykład GET /products, a dalej trzymaj się kontraktu.

Uwierzytelnianie

Każde żądanie niesie Twój klucz w nagłówku X-Api-Key. v1 dostarcza dokładnie cztery zakresy odczytu — produkty, zamówienia, klienci i doręczenia webhooków. Brakujący zakres odpowiada 403, unieważniony klucz jest odrzucany natychmiast. Trzymaj klucze po stronie serwera: nie mają miejsca w przeglądarce ani w publicznym repozytorium.

products:readorders:readcustomers:readwebhooks:read

Paginacja

Endpointy listujące stronicują: przechodź je parametrem page i czytaj kopertę zwracaną z każdą kolekcją — mówi, gdzie jesteś, by Twoja integracja mogła się zsynchronizować bez zgadywania. Dokładne parametry każdego endpointu są udokumentowane w kontrakcie.

Błędy i limity zapytań

Błędy zwracają ustrukturyzowane ciało JSON, które można parsować — nigdy akapit do rozdrapywania. Odpowiedź 429 to stabilny kontrakt: zawsze ten sam kształt, z nagłówkami X-RateLimit-* i Retry-After, który mówi dokładnie, kiedy wrócić. Napieranie nie odblokowuje danych — zastosuj backoff.

Klucze sandbox

W okresie przed uruchomieniem klucze sandbox są wydawane po walidacji naszego zespołu i działają z dedykowanym budżetem limitów, oddzielnym od kluczy produkcyjnych — poznawaj API na swoim sklepie bez dotykania ruchu na żywo ani limitów.

Przykłady per język

Jeden snippet na platformę, tylko zakresy odczytu: każdy pobiera Twój katalog produktów. Zastąp <api-base> hostem API Twojego sklepu z panelu administracyjnego → sekcja Deweloperzy.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

v1 jest tylko do odczytu z założenia: products:read, orders:read, customers:read i webhooks:read to jedyne istniejące zakresy. Zakresy zapisu byłyby jawnie udokumentowaną decyzją v1.x — nic nie jest planowane po cichu.