Używamy plików cookie, aby zapewnić podstawowe usługi i analitykę. Możesz w dowolnej chwili zmienić ustawienia. Lista plików cookie
API dla partnerów łączy BoutiqVerse z Twoim magazynem, systemem ERP albo własnym sklepem. Jest celowo małe: katalog, stany, zamówienia i nadanie paczki – tyle, ile potrzeba do synchronizacji.
Klucz utworzysz w panelu: Ustawienia → Klucze API. Pokazujemy go tylko raz, przy tworzeniu – zapisz go od razu, bo przechowujemy wyłącznie jego skrót. Każdy klucz ma swoje zakresy uprawnień, a odwołany klucz przestaje działać.
Klucz wysyłasz w nagłówku Authorization (Bearer) albo X-API-Key. Limit to 120 zapytań na minutę na klucz – po jego przekroczeniu dostaniesz odpowiedź 429.
https://www.boutiqverse.com/api/partner
Authorization: Bearer $BOUTIQVERSE_API_KEY
X-API-Key: $BOUTIQVERSE_API_KEYKlucz testowy utworzysz w tym samym miejscu (Ustawienia → Klucze API), zaznaczając „Klucz testowy”. Zaczyna się od btk_test_ i działa na danych sklepu pokazowego, nie na Twoim sklepie. Odczyt katalogu i zamówień jest prawdziwy, a zmiana stanów i nadanie paczki dostają taką samą odpowiedź jak naprawdę – z polem sandbox: true – ale niczego nie zapisują. Odpowiedź ma też nagłówek X-BoutiqVerse-Sandbox.
Webhook sprawdzisz przyciskiem „Wyślij zdarzenie testowe” w Ustawienia → Webhooki: przyjdzie zdarzenie webhook.test z tym samym podpisem co prawdziwe.
Wymagany zakres: products:read
Katalog butiku ze stanami rozmiarów, od najnowszych produktów. Parametry: limit (od 1 do 500, domyślnie 100) i offset.
curl "https://www.boutiqverse.com/api/partner/products?limit=100&offset=0" \
-H "Authorization: Bearer $BOUTIQVERSE_API_KEY"
{
"success": true,
"data": {
"products": [
{
"id": "5f0c8a52-…",
"name": "Sukienka Lena",
"slug": "sukienka-lena-5f0c8a",
"price": "249.00",
"status": "active",
"stock_quantity": 6,
"in_stock": true,
"variants": [
{ "id": "9a1e…", "sku": "LENA-CZ-S", "size": "S", "color": "Czarny", "stock": 2, "priceOverride": null }
]
}
],
"limit": 100,
"offset": 0
}
}Wymagany zakres: stock:write
Ustawia stany do 1000 kodów SKU w jednym zapytaniu. Stan jest ustawiany, nie dodawany – ponowione zapytanie niczego nie podwaja. Sztuki w zamówieniach czekających na płatność i w rezerwacjach do przymiarki odejmujemy sami. Odpowiedź podaje, ile rozmiarów zmieniliśmy, których kodów SKU nie znamy i które stany są błędne.
curl -X PATCH "https://www.boutiqverse.com/api/partner/stock" \
-H "Authorization: Bearer $BOUTIQVERSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "updates": [ { "sku": "LENA-CZ-S", "stock": 4 }, { "sku": "LENA-CZ-M", "stock": 0 } ] }'
{
"success": true,
"data": { "updated": 2, "notFound": [], "invalid": [] }
}Wymagany zakres: orders:read
Zamówienia z Twoimi produktami – tylko Twoje pozycje i stan Twojej paczki. Parametry: since (data w formacie ISO) i limit (od 1 do 500).
curl "https://www.boutiqverse.com/api/partner/orders?since=2026-10-01T00:00:00Z&limit=100" \
-H "X-API-Key: $BOUTIQVERSE_API_KEY"
{
"success": true,
"data": {
"orders": [
{
"id": "c41d…",
"order_number": "ORD-2026-001234",
"status": "processing",
"created_at": "2026-10-28T09:12:44.000Z",
"shipping_country": "PL",
"tracking_number": null,
"carrier": null,
"items": [
{ "productId": "5f0c8a52-…", "sku": "LENA-CZ-S", "name": "Sukienka Lena", "quantity": 1, "price": "249.00", "size": "S", "color": "Czarny" }
]
}
]
}
}Wymagany zakres: orders:write
Przekazuje numer przesyłki. Paczka staje się wysłana tak samo jak w panelu: klientka dostaje e-mail. Gdy klientka odstąpiła od umowy przed wysyłką albo zamówienie nie może zostać wysłane, dostaniesz odpowiedź 409 z kodem błędu.
curl -X POST "https://www.boutiqverse.com/api/partner/orders/c41d…/ship" \
-H "Authorization: Bearer $BOUTIQVERSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "trackingNumber": "520000011395200025754312", "carrier": "inpost" }'
{
"success": true,
"data": { "trackingNumber": "520000011395200025754312", "trackingUrl": "https://…", "carrier": "inpost" }
}Błąd to JSON z polami success (false), message i zwykle code.
Adres, sekret i zdarzenia ustawisz w panelu: Ustawienia → Webhooki. Wysyłamy POST z JSON-em na adres https. Nagłówek X-Butiki-Signature to HMAC-SHA256 surowej treści zapytania z Twoim sekretem (szesnastkowo), X-Butiki-Event – rodzaj zdarzenia, a X-Butiki-Delivery – identyfikator dostawy. Dostawa udaje się, gdy Twój serwer odpowie kodem 2xx w ciągu 15 sekund. Inaczej próbujemy ponownie po minucie, 5 minutach, 30 minutach i 3 godzinach – w sumie do 5 prób.
order.creatednowe zamówienieorder.paidzamówienie opłaconeorder.shippedpaczka wysłanaorder.refundedzwrot pieniędzy za zamówienieorder.cancelledzamówienie anulowaneproduct.updatedprodukt zmieniony – także przez synchronizację ze sklepureturn.creatednowe zgłoszenie zwrotu albo reklamacjireturn.refundedzwrot pieniędzy za zwrotPOST https://twoj-serwer.pl/boutiqverse
Content-Type: application/json
X-Butiki-Event: order.paid
X-Butiki-Delivery: 7b0f…
X-Butiki-Signature: 3f9a… (HMAC-SHA256, hex)
{ "id": "7b0f…", "type": "order.paid", "payload": { … }, "createdAt": "2026-10-28T09:13:02.000Z" }// Node.js: podpis liczony z SUROWEJ tresci zadania
const crypto = require("crypto")
function isFromBoutiqVerse(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
const a = Buffer.from(expected)
const b = Buffer.from(String(signatureHeader || ""))
return a.length === b.length && crypto.timingSafeEqual(a, b)
}Potrzebujesz innej metody albo integracji z inną platformą? Dodamy ją za darmo. Napisz do nas