Copy page

Podstawy API

Podpisywanie żądań (HMAC)

Każde żądanie API v2 to HTTP POST z Content-Type: application/x-www-form-urlencoded i dokładnie czterema polami:

Pole	Wartość
app_id	ID aplikacji z panelu Apaczka
request	Payload metody, zserializowany do stringa JSON
expires	Znacznik czasu Unix ważności żądania (maks. +15 minut)
signature	Podpis HMAC-SHA256 — patrz niżej

Podpis

String do podpisania to cztery wartości połączone :

Code
app_id : route : request : expires

gdzie route to ścieżka metody wraz z parametrami ścieżki i końcowym ukośnikiem — np. order_send/, points/INPOST/ albo waybill/123456/. Podpis to HMAC-SHA256 tego stringa (klucz: app_secret), zapisany szesnastkowo małymi literami.

Przykład (PHP)

Code
$appId     = 'your-app-id';
$appSecret = 'your-app-secret';
$route     = 'order_send/';                 // końcowy ukośnik jest wymagany
$payload   = json_encode($order);           // payload metody
$expires   = time() + 900;                  // teraz + 15 minut

$stringToSign = sprintf('%s:%s:%s:%s', $appId, $route, $payload, $expires);
$signature    = hash_hmac('sha256', $stringToSign, $appSecret);

$response = $http->post('https://www.apaczka.pl/api/v2/' . $route, [
    'form_params' => [
        'app_id'    => $appId,
        'request'   => $payload,
        'expires'   => $expires,
        'signature' => $signature,
    ],
]);

Częste pułapki

• Brak końcowego ukośnika w route — order_send podpisuje się inaczej niż order_send/. Serwer podpisuje z ukośnikiem.
• Parametry ścieżki należą do route — dla waybill/123456/ podpisujesz pełną ścieżkę z ID zamówienia.
• expires zbyt daleko w przyszłości — limit to 15 minut.
• HTTP 200 nie oznacza sukcesu — zobacz Semantykę błędów.

Pełna referencja metod: API v2 (EN).