Instrukcja składania zamówień przez API

Spis treści

1. Jak to działa
2. Zasady współpracy
3. Dostęp i bezpieczeństwo
4. Podpis żądania (HMAC)
5. Dane z katalogu: cena, pakowanie, stan
6. Format zamówienia
7. Reguły walidacji i kody błędów
8. Odpowiedzi i kody HTTP
9. Statusy zamówienia
10. Ponawianie i idempotencja
11. Limity
12. Testy i uruchomienie
13. Najczęstsze problemy
14. Kontakt

Zmiany w API opisuje historia zmian.

2. Zasady współpracy

Reguły handlowe, które obowiązują każde zamówienie złożone przez API.

4. Podpis żądania (HMAC)

Wymagany dla POST /v1/orders i POST /v1/orders/validate. Dzięki podpisowi sam wyciek klucza nie pozwala złożyć zamówienia, a przechwyconego żądania nie da się użyć po upływie 5 minut (okno X-Timestamp); w tym oknie powtórka nie utworzy duplikatu dzięki idempotencji po externalOrderNumber.

Algorytm

1. Przygotuj body jako tekst JSON (UTF-8) — dokładnie ten tekst wyślesz w żądaniu.
2. Weź aktualny czas Unix w sekundach, np. 1790172000. Wyślesz go w nagłówku X-Timestamp.
3. Zbuduj tekst do podpisu: <X-Timestamp>.<ścieżka>.<body>, gdzie ścieżka to /v1/orders albo /v1/orders/validate (bez domeny i parametrów).
4. Policz HMAC-SHA256 tego tekstu z sekretem podpisu jako kluczem; wynik zapisz szesnastkowo małymi literami.
5. Wyślij nagłówek X-Signature: sha256=<wynik>.

X-Partner-Key: pk_…
X-Timestamp: 1790172000
X-Signature: sha256=hex( HMAC_SHA256( sekret, "1790172000" + "." + "/v1/orders" + "." + body ) )
Content-Type: application/json

Wektor testowy

Sprawdź swoją implementację na tych danych — musisz otrzymać dokładnie podany podpis.

Przykłady

# bash + openssl — walidacja próbna
BODY='{"externalOrderNumber":"TEST-0001","currency":"PLN","lines":[{"lineNo":1,"sku":"A02-003","quantity":12}]}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS./v1/orders/validate.$BODY" | openssl dgst -sha256 -hmac "$AKCES_SIGNING_SECRET" | sed 's/^.* //')

curl -sS -X POST "https://api.akces.pl/v1/orders/validate" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: $AKCES_API_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: sha256=$SIG" \
  --data-binary "$BODY"        # --data-binary: wysyła dokładnie te bajty

// Node.js 18+ (fetch wbudowany)
import crypto from "node:crypto";

async function sendOrder(order, path = "/v1/orders") {
  const body = JSON.stringify(order);                 // ten sam tekst podpisujemy i wysyłamy
  const ts = String(Math.floor(Date.now() / 1000));
  const signature = crypto
    .createHmac("sha256", process.env.AKCES_SIGNING_SECRET)
    .update(ts + "." + path + "." + body, "utf8")
    .digest("hex");

  const res = await fetch("https://api.akces.pl" + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Partner-Key": process.env.AKCES_API_KEY,
      "X-Timestamp": ts,
      "X-Signature": "sha256=" + signature,
    },
    body,
  });
  return { status: res.status, json: await res.json() };
}

// PHP 8+ z rozszerzeniem curl
function sendOrder(array $order, string $path = "/v1/orders"): array {
    $body = json_encode($order, JSON_UNESCAPED_UNICODE | JSON_PRESERVE_ZERO_FRACTION);
    $ts = (string) time();
    $signature = hash_hmac("sha256", $ts . "." . $path . "." . $body, getenv("AKCES_SIGNING_SECRET"));

    $ch = curl_init("https://api.akces.pl" . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $body,          // dokładnie ten sam tekst, który podpisano
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 90,
        CURLOPT_HTTPHEADER => [
            "Content-Type: application/json",
            "X-Partner-Key: " . getenv("AKCES_API_KEY"),
            "X-Timestamp: " . $ts,
            "X-Signature: sha256=" . $signature,
        ],
    ]);
    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return ["status" => $status, "json" => json_decode($response, true)];
}

# Python 3 + requests
import hashlib, hmac, json, os, time, requests

def send_order(order, path="/v1/orders"):
    body = json.dumps(order, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    ts = str(int(time.time()))
    message = ts.encode() + b"." + path.encode() + b"." + body
    signature = hmac.new(os.environ["AKCES_SIGNING_SECRET"].encode(), message, hashlib.sha256).hexdigest()
    r = requests.post("https://api.akces.pl" + path, data=body, timeout=90, headers={
        "Content-Type": "application/json",
        "X-Partner-Key": os.environ["AKCES_API_KEY"],
        "X-Timestamp": ts,
        "X-Signature": "sha256=" + signature,
    })
    return r.status_code, r.json()

// .NET 6+ (System.Text.Json, HttpClient)
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

// Nazwy pól jak w API (camelCase), puste pola opcjonalne pomijamy
static readonly JsonSerializerOptions AkcesJson = new()
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
};

static async Task<HttpResponseMessage> SendOrder(HttpClient http, object order, string path = "/v1/orders")
{
    var body = JsonSerializer.Serialize(order, AkcesJson);
    var ts = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("AKCES_SIGNING_SECRET")!));
    var signature = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(ts + "." + path + "." + body))).ToLowerInvariant();

    var request = new HttpRequestMessage(HttpMethod.Post, "https://api.akces.pl" + path)
    {
        Content = new StringContent(body, Encoding.UTF8, "application/json")
    };
    request.Headers.Add("X-Partner-Key", Environment.GetEnvironmentVariable("AKCES_API_KEY"));
    request.Headers.Add("X-Timestamp", ts);
    request.Headers.Add("X-Signature", "sha256=" + signature);
    return await http.SendAsync(request);
}

Najczęstsze błędy podpisu

• Podpisanie obiektu, a wysłanie innej serializacji (np. biblioteka HTTP ponownie serializuje JSON, zmienia kolejność pól albo formatowanie). Podpisuj i wysyłaj ten sam tekst.
• Inna ścieżka w podpisie niż w adresie (np. podpis dla /v1/orders/validate, a wysyłka na /v1/orders).
• Znacznik czasu w milisekundach zamiast w sekundach (TIMESTAMP_INVALID) albo rozjechany zegar serwera (TIMESTAMP_EXPIRED).
• Wynik HMAC zakodowany w Base64 zamiast szesnastkowo (wymagane 64 znaki hex).
• Body w kodowaniu innym niż UTF-8 (polskie znaki w uwagach).

6. Format zamówienia

POST /v1/orders (i /v1/orders/validate), treść żądania (body) JSON w UTF-8, maks. 256 KB. Nieznane pola są błędem — literówka w nazwie pola nie przejdzie niezauważona.

Nazwy pól podawaj dokładnie jak w tabeli (camelCase) — nieznane pola dają 400. Puste pola opcjonalne najlepiej pomijaj; wartość null przyjmujemy w polach notes, contact, contact.name, contact.phone, contact.email, lines[].lineNo, lines[].ean, lines[].unitPriceNetto i expectedTotalNetto.

Przykład

{
  "externalOrderNumber": "FK/2026/000123",
  "currency": "PLN",
  "notes": "Odbiór we wtorek rano",
  "contact": { "name": "Jan Nowak", "phone": "+48 600 100 200", "email": "magazyn@example.com" },
  "lines": [
    { "lineNo": 1, "sku": "A02-003", "ean": "5907489847698", "quantity": 12 },
    { "lineNo": 2, "sku": "B14-01", "quantity": 96 }
  ]
}

8. Odpowiedzi i kody HTTP

Każda odpowiedź to JSON. Błędy mają pola error (opis) i code (kod do obsługi w programie).

Przykład odpowiedzi 202 (czeka na zatwierdzenie)

{
  "data": {
    "id": "cmf2x9k0a0001abcd1234efgh",          // zapisz — do GET /v1/orders/{id}
    "externalOrderNumber": "FK/2026/000123",
    "status": "PENDING_REVIEW",
    "erpOrderNumber": null,                          // numer ZO — po skierowaniu do realizacji
    "akcesOrderNumber": "CX/0412/09/26",           // numer Akces — nadawany od razu
    "fulfillmentStatus": null,                       // null do czasu przyjęcia (ACCEPTED)
    "currency": "PLN",
    "totalNetto": 164.04,
    "lines": [                                     // ceny Akces zastosowane w zamówieniu
      { "lineNo": 1, "sku": "A02-003", "quantity": 12, "unitPriceNetto": 7.67,
        "basePriceNetto": 10.95, "discountPercent": 30, "discountSource": "company", "lineTotalNetto": 92.04 },
      { "lineNo": 2, "sku": "B14-01", "quantity": 96, "unitPriceNetto": 0.75,
        "basePriceNetto": 1.5, "discountPercent": 50, "discountSource": "promotion", "lineTotalNetto": 72 }
    ],
    "errors": [],
    "declineReason": null,
    "createdAt": "2026-09-24T08:15:00.000Z",
    "updatedAt": "2026-09-24T08:15:00.000Z"
  },
  "timestamp": "2026-09-24T08:15:00.120Z"
}

Ceny i rabaty w tym przykładzie są umowne.

Numery zamówienia w odpowiedzi

• id — identyfikator do GET /v1/orders/{id}.
• akcesOrderNumber — numer referencyjny zamówienia w Akces, nadawany przy zapisie (także przy 202), np. CX/0412/09/26. Podawaj go w kontakcie z działem obsługi klienta.
• erpOrderNumber — numer zamówienia sprzedaży (ZO, np. ZO/0123/09/26); pojawia się po skierowaniu zamówienia do realizacji.

10. Ponawianie i idempotencja

externalOrderNumber jest kluczem idempotencji — dzięki niemu ponowienie nigdy nie tworzy duplikatu.

„Ta sama treść” = te same pozycje w tej samej kolejności (sku, quantity, lineNo, ean), te same uwagi (notes), kontakt (contact) i waluta. Ceny informacyjne (unitPriceNetto, expectedTotalNetto) nie są porównywane — ponowienie z inną ceną informacyjną to nadal powtórka (HTTP 200). Przy ponowieniu najlepiej wysyłaj dokładnie ten sam JSON co za pierwszym razem — zapisz go przed wysłaniem.

Zalecany sposób ponawiania

1. Przekroczony czas oczekiwania (timeout), błąd sieci, HTTP 500/502/504: ponów z tym samym externalOrderNumber i tą samą treścią, z nowym znacznikiem czasu i podpisem. Po 502/504 i po przekroczeniu czasu zamówienie mogło już zostać złożone — ponowienie zwróci wtedy 200 z idempotentReplay: true. Odstępy: np. 5 s, 30 s, 2 min, 10 min.
2. HTTP 429 i 503: odczekaj co najmniej czas z nagłówka Retry-After, potem ponawiaj z rosnącymi odstępami (np. 2 min, 10 min) — przy 503 z tym samym externalOrderNumber i treścią.
3. HTTP 400/401/403/404/405/409/413/415/422: nie ponawiaj bez zmian — popraw żądanie lub konfigurację.
4. Jeśli nie masz pewności, czy zamówienie dotarło, sprawdź GET /v1/orders?externalOrderNumber=…. Możesz dostać kilka prób z tym numerem (np. odrzuconą i poprawioną); obowiązuje ta ze statusem ACCEPTED lub PENDING_REVIEW.
5. Ustaw timeout żądania na co najmniej 90 s.

12. Testy i uruchomienie

Nie ma osobnego środowiska testowego — testuj na produkcyjnym katalogu, cenach i stanach przez walidację próbną.

• POST /v1/orders/validate przyjmuje to samo body i podpis liczony tym samym algorytmem (ze ścieżką /v1/orders/validate), ale niczego nie zapisuje i nie rezerwuje. Odpowiedź (HTTP 200) w polu data: valid, currency, totalNetto, lines[] (lineNo, sku, quantity, unitPriceNetto, basePriceNetto, discountPercent, discountSource, lineTotalNetto, orderStep, valid) i errors.
• Walidacja próbna nie sprawdza, czy externalOrderNumber był już użyty (409 lub powtórka 200), ani limitu prób na 24 h.
• Pierwsze prawdziwe zamówienie uzgodnij z działem obsługi klienta — zobaczymy je od razu i potwierdzimy, że wszystko się zgadza.

Lista kontrolna przed startem

• Klucz API i sekret podpisu zapisane po stronie serwera (nie w kodzie, nie w repozytorium).
• Serwery wysyłające żądania mają adresy IP uzgodnione z Akces.
• Zegar serwera synchronizowany przez NTP.
• Implementacja podpisu daje wynik z wektora testowego.
• Mapowanie produktów po SKU (opcjonalnie z kontrolą EAN).
• Pełne pobranie katalogu co 15–30 minut i sprawdzenie koszyka przez POST /v1/orders/validate przed wysłaniem.
• Ilości zaokrąglane do wielokrotności orderStep, co najmniej minOrderQuantity, najwyżej availableStock.
• Zapisywanie w Twoim systemie cen Akces z odpowiedzi na zamówienie (unitPriceNetto, totalNetto) i numeru akcesOrderNumber.
• Walidacja próbna przechodzi dla typowego zamówienia (data.valid: true).
• Obsługa odpowiedzi 201 / 202 / 422 (wyświetlenie błędów użytkownikowi) oraz 409.
• Ponawianie z tym samym externalOrderNumber po błędach sieci i 5xx (przy 429 i 503 po odczekaniu Retry-After).
• Odpytywanie statusów (GET /v1/orders?updatedSince=…) i reakcja na DO_ODBIORU.

14. Kontakt

Specyfikacja techniczna: OpenAPI 3.0 · Swagger UI · Dokumentacja katalogu produktów · Historia zmian.