# 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 `:`

```
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)

```php
$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,
    ],
]);
```

:::tip

Podpisuj **dokładnie ten string, który wysyłasz** jako `request`. Ponowna
serializacja payloadu po podpisaniu (inna kolejność kluczy, białe znaki,
escapowanie) to najczęstsza przyczyna błędu `Invalid 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](/pl/legacy/error-semantics).

Pełna referencja metod:
[API v2](/pl/reference/v2-legacy) (EN).