Katalog, ceny, stany
i zamówienia przez API.

Szybki start

Trzy kroki, żeby zacząć pobierać dane.

# Pobierz pierwsze 5 produktów
curl "https://api.akces.pl/v1/products?limit=5" \
  -H "X-Partner-Key: pk_TWOJ_KLUCZ"

const res = await fetch(
  "https://api.akces.pl/v1/products?limit=5",
  { headers: { "X-Partner-Key": process.env.AKCES_API_KEY } }
);
const { data, pagination } = await res.json();
console.log(`Mam ${pagination.total} produktów`);

// Wymagane: PHP 8+ z curl
$ch = curl_init("https://api.akces.pl/v1/products?limit=5");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Partner-Key: " . getenv("AKCES_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
echo "Mam {$data['pagination']['total']} produktów\n";

import requests, os

r = requests.get(
    "https://api.akces.pl/v1/products",
    params={"limit": 5},
    headers={"X-Partner-Key": os.environ["AKCES_API_KEY"]},
)
data = r.json()
print(f"Mam {data['pagination']['total']} produktów")

# Zmiany od poprzedniego pobrania
# (updatedSince = pole timestamp z poprzedniej odpowiedzi minus 5 min)
curl "https://api.akces.pl/v1/products?updatedSince=2026-11-05T15:20:54Z&limit=200" \
  -H "X-Partner-Key: pk_TWOJ_KLUCZ"

# Co 15–30 min — pełna lista (kolejne strony: page=2, 3…)
curl "https://api.akces.pl/v1/products?limit=200&page=1" \
  -H "X-Partner-Key: pk_TWOJ_KLUCZ"

Zamówienia

Dla kont z włączonymi zamówieniami. Zamówienie trafia na konto Twojej firmy (przypisanej do klucza) i jest zawsze zakładane jako odbiór osobisty (Magazyn Akces, ul. Sławęcińska 3, 05-850 Macierzysz), płatne przelewem (termin według warunków Twojego konta), dokument: faktura, ceny netto. Adresu dostawy nie podaje się.

Reguły walidacji

Sprawdzamy wszystkie reguły naraz i zwracamy pełną listę błędów. Jeden błąd odrzuca całe zamówienie — poprawne pozycje nie są zapisywane osobno.

• SKU musi istnieć w katalogu (GET /v1/products) i być dostępny w sprzedaży przez API; każdy SKU najwyżej raz w zamówieniu. Opcjonalny ean sprawdzamy krzyżowo z kartoteką.
• Ilość musi być wielokrotnością orderStep — liczby jednostek w najmniejszym zdefiniowanym opakowaniu (1 = bez ograniczeń). Np. opakowanie 5 szt., pudełko 20, karton 100 → możesz zamówić dowolną wielokrotność 5: 5, 10, 15, 20…, ale nie 9.
• Minimalna ilość — nie mniej niż minOrderQuantity. Dotyczy kategorii Kwiaty sztuczne / Główki kwiatowe: każdy kolor zamawiasz w ilości co najmniej 5 opakowań (minOrderQuantity = 5 × packaging.package), także produkty z pudełkiem — pudełko lub karton spełnia warunek, jeśli mieści co najmniej 5 opakowań. W pozostałych produktach minOrderQuantity = orderStep.
• Stan — ilość nie może przekraczać availableStock w chwili złożenia zamówienia (wartość z wcześniej pobranego katalogu mogła się zmienić). Towar rezerwujemy w chwili złożenia zamówienia.
• Cena — zawsze obowiązuje cena Akces z chwili złożenia zamówienia (odpowiedź 201/202): cennik + najkorzystniejszy rabat (konto, promocja/wyprzedaż, oferta), naliczany automatycznie. Ceny w zamówieniu nie musisz podawać (pole unitPriceNetto jest opcjonalne i tylko informacyjne — nie porównujemy go z ceną Akces). Zastosowane ceny wracają w odpowiedzi. Zatwierdzenie przez Akces (PENDING_REVIEW → ACCEPTED) nie zmienia cen ani rezerwacji.
• Waluta — tylko PLN. Nieznane pola w JSON są błędem (chroni przed literówkami w nazwach pól).

Podpis żądania (HMAC)

Oprócz X-Partner-Key każde żądanie POST (zamówienie i walidacja próbna) wymaga nagłówków:

X-Timestamp: 1790160000                // Unix, sekundy — okno ±300 s
X-Signature: sha256=<hex HMAC-SHA256(sekret, X-Timestamp + "." + ścieżka + "." + surowe_body)>

Sekret podpisu (whsec_…) przekazujemy osobnym kanałem. Ścieżka to /v1/orders albo /v1/orders/validate (podpis walidacji próbnej nie zadziała jako zamówienie). Podpisz dokładnie te bajty, które wysyłasz jako body. Wywołania tylko z serwera — żądania z przeglądarki (z nagłówkiem Origin) są odrzucane (403 BROWSER_NOT_ALLOWED). Wektor testowy do sprawdzenia Twojej implementacji znajdziesz w instrukcji zamówień.

Przykład wywołuje walidację próbną. Żeby złożyć prawdziwe zamówienie, zmień ścieżkę na /v1/orders w podpisie i w adresie — zamówienie trafi na produkcję i zarezerwuje towar.

import crypto from "node:crypto";

const body = JSON.stringify({
  externalOrderNumber: "TEST-0001",
  currency: "PLN",
  notes: "Odbiór we wtorek",
  lines: [{ lineNo: 1, sku: "A02-003", quantity: 12 }],
});
const ts = String(Math.floor(Date.now() / 1000));
const sig = crypto.createHmac("sha256", process.env.AKCES_SIGNING_SECRET)
  .update(ts + "./v1/orders/validate." + body).digest("hex");

const res = await fetch("https://api.akces.pl/v1/orders/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Partner-Key": process.env.AKCES_API_KEY,
    "X-Timestamp": ts,
    "X-Signature": "sha256=" + sig,
  },
  body,
});
const json = await res.json();   // 200 → json.data.valid, json.data.errors, json.data.lines (ceny Akces)

$body = json_encode([
  "externalOrderNumber" => "TEST-0001",
  "currency" => "PLN",
  "lines" => [["lineNo" => 1, "sku" => "A02-003", "quantity" => 12]],
], JSON_UNESCAPED_UNICODE);
$ts = (string) time();
$sig = hash_hmac("sha256", $ts . "./v1/orders/validate." . $body, getenv("AKCES_SIGNING_SECRET"));

$ch = curl_init("https://api.akces.pl/v1/orders/validate");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $body,          // dokładnie ten sam string, który podpisano
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Partner-Key: " . getenv("AKCES_API_KEY"),
    "X-Timestamp: " . $ts,
    "X-Signature: sha256=" . $sig,
  ],
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

import hashlib, hmac, json, os, time, requests

body = json.dumps({
    "externalOrderNumber": "TEST-0001",
    "currency": "PLN",
    "lines": [{"lineNo": 1, "sku": "A02-003", "quantity": 12}],
}, ensure_ascii=False).encode("utf-8")
ts = str(int(time.time()))
sig = hmac.new(os.environ["AKCES_SIGNING_SECRET"].encode(), ts.encode() + b"./v1/orders/validate." + body, hashlib.sha256).hexdigest()

r = requests.post("https://api.akces.pl/v1/orders/validate", data=body, headers={
    "Content-Type": "application/json",
    "X-Partner-Key": os.environ["AKCES_API_KEY"],
    "X-Timestamp": ts,
    "X-Signature": "sha256=" + sig,
})

Odpowiedzi

• 201 — przyjęte (status: ACCEPTED), towar zarezerwowany. Numer referencyjny zamówienia w Akces (np. CX/0412/09/26) dostajesz od razu w akcesOrderNumber; numer zamówienia w systemie Akces (ZO, np. ZO/0123/09/26) pojawi się w erpOrderNumber po przekazaniu do realizacji.
• 202 — poprawne, towar zarezerwowany, czeka na zatwierdzenie przez Akces (PENDING_REVIEW); numer referencyjny jest już w akcesOrderNumber. Wynik sprawdzisz w GET /v1/orders.
• 422 — odrzucone (REJECTED); data.errors zawiera wszystkie błędy z numerem pozycji. Popraw i wyślij ponownie — możesz użyć tego samego numeru.
• 200 — powtórzone żądanie (ten sam numer i ta sama treść) — dostajesz aktualny stan pierwotnego zamówienia (idempotentReplay: true), duplikat nie powstaje. Ceny informacyjne (unitPriceNetto, expectedTotalNetto) nie wchodzą do porównania treści.
• 409 — numer użyty już w zamówieniu ACCEPTED lub PENDING_REVIEW, z inną treścią. Zmiany w takim zamówieniu — kontakt z działem obsługi klienta.
• 5xx (500, 502, 503, 504) — chwilowa niedostępność. Ponów z tym samym externalOrderNumber i tą samą treścią (nowy znacznik czasu i podpis) — to bezpieczne. Przy 503 i 429 odczekaj co najmniej czas z nagłówka Retry-After.

{
  "error": "Order rejected. See errors for details.",
  "code": "ORDER_REJECTED",
  "data": {
    "status": "REJECTED",
    "errors": [
      { "code": "INSUFFICIENT_STOCK", "lineNo": 1, "sku": "A02-003",
        "message": "Quantity of A02-003 exceeds the available quantity (availableStock).",
        "details": { "maxOrderable": 240 } },
      { "code": "PACKAGING_MULTIPLE", "lineNo": 2, "sku": "B14-01",
        "message": "Quantity 100 of B14-01 is not a multiple of the packaging unit (96).",
        "details": { "orderStep": 96, "packaging": { "package": null, "innerCarton": 96, "outerCarton": 1152 },
                     "suggestedQuantities": [96, 192] } }
    ],
    …   // odpowiedź skrócona: data zawiera też id, externalOrderNumber, lines, totalNetto, createdAt, updatedAt
  }
}

Kody błędów: UNKNOWN_SKU, EAN_MISMATCH, PRODUCT_NOT_AVAILABLE, DUPLICATE_LINE, PACKAGING_MULTIPLE, BELOW_MINIMUM_QUANTITY (z minOrderQuantity), INSUFFICIENT_STOCK (z maxOrderable), CONTRACTOR_BLOCKED. Pełna tabela kodów HTTP: /docs/zamowienia.

Limity: 10 zamówień/min, 30 walidacji/min, 60 odczytów statusu/min; maks. 500 prób zamówień w ciągu ostatnich 24 h (okno kroczące, przyjęte i odrzucone łącznie); maks. 500 pozycji i 256 KB na zamówienie.

Pomoc i kontakt

Pytania, problemy, sugestie?