# Przykłady implementacji

:::info

Poniższe przykłady są napisane w **PHP**. Do testowania
poszczególnych metod na żywo (wraz z generowanymi snippetami w innych
językach) służy panel *Try it* w [API Reference](/pl/reference/v2-legacy).

:::

## Najprościej: oficjalne SDK

Jeśli integrujesz się z PHP, pomiń ręczne podpisywanie — oficjalne
[SDK](/pl/sdk) obsługuje podpisy, znaczniki wygaśnięcia i mapowanie błędów
za Ciebie, a odpowiedzi zwraca jako typowane obiekty:

```bash
composer require alsendo/alsendo-one-sdk guzzlehttp/guzzle guzzlehttp/psr7
```

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use AlsendoOne\SDK\AlsendoClient;
use AlsendoOne\SDK\Exception\AlsendoException;

$client = new AlsendoClient('your_app_id', 'your_app_secret');

try {
    // 1. Wybierz usługę
    $structure = $client->getServiceStructure();

    // 2. Wyceń przesyłkę (ceny są zwracane w groszach!)
    $valuation = $client->getValuation($order);

    // 3. Utwórz zamówienie
    $created = $client->sendOrder($order);
    $orderId = $created->getId();

    // 4. Pobierz etykietę (PDF zakodowany w base64)
    $waybill = $client->getWaybill($orderId);
    file_put_contents('label.pdf', base64_decode($waybill->getWaybill()));
} catch (AlsendoException $e) {
    echo 'Błąd Apaczka API: ' . $e->getMessage();
}
```

Dalsza część strony pokazuje te same przepływy w czystym PHP + cURL —
przydatne, gdy nie możesz użyć Composera albo integrujesz się z innego
języka.

## Wspólny helper: podpisane żądanie w kopercie

Każde wywołanie API v2 to ten sam `POST` z kopertą — opakuj go raz
(szczegóły algorytmu:
[Podpisywanie żądań](/pl/legacy/hmac-signing)):

```php
<?php
/**
 * Wysyła podpisane żądanie do Apaczka API v2.
 * $route musi zawierać parametry ścieżki i końcowy ukośnik, np. "order_send/".
 */
function apaczka_request(string $route, array $payload = []): array
{
    $appId     = getenv('APACZKA_APP_ID');
    $appSecret = getenv('APACZKA_APP_SECRET');

    $request = json_encode($payload);
    $expires = time() + 900; // maks. +15 minut

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

    $ch = curl_init('https://www.apaczka.pl/api/v2/' . $route);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS     => http_build_query([
            'app_id'    => $appId,
            'request'   => $request,
            'expires'   => $expires,
            'signature' => $signature,
        ]),
    ]);
    $body = curl_exec($ch);
    curl_close($ch);

    $response = json_decode($body, true);

    // Status HTTP to zawsze 200 — rzeczywisty wynik jest w ciele odpowiedzi.
    if (($response['status'] ?? 0) !== 200) {
        throw new RuntimeException(sprintf(
            'Błąd Apaczka API %d: %s',
            $response['status'] ?? 0,
            $response['message'] ?? 'Unknown error'
        ));
    }

    return $response['response'];
}
```

## Pobranie dostępnych usług

```php
$structure = apaczka_request('service_structure/');

foreach ($structure['services'] as $service) {
    echo $service['id'] . ': ' . $service['name'] . PHP_EOL;
}
```

## Wycena zamówienia

```php
$order = [
    'order' => [
        'service_id' => 65,
        'address' => [
            'sender' => [
                'name'           => 'Firma Testowa Sp. z o.o.',
                'line1'          => 'ul. Marszalkowska 1',
                'postal_code'    => '05-500',
                'city'           => 'Warszawa',
                'country_code'   => 'PL',
                'is_residential' => false,
                'contact_person' => 'Jan Kowalski',
                'email'          => 'sender@example.pl',
                'phone'          => '500000000',
            ],
            'receiver' => [
                'name'           => 'Apaczka Sp. z o.o.',
                'line1'          => 'Legionow Polskich 2',
                'postal_code'    => '01-479',
                'city'           => 'Warszawa',
                'country_code'   => 'PL',
                'is_residential' => false,
                'contact_person' => 'Adam Nowak',
                'email'          => 'receiver@example.pl',
                'phone'          => '321321321',
            ],
        ],
        'pickup'   => ['type' => 'SELF'],
        'shipment' => [
            [
                'dimension1' => 10,
                'dimension2' => 10,
                'dimension3' => 10,
                'weight'     => 1,
                'is_nstd'    => 0,
            ],
        ],
        'content' => 'Elektronika',
    ],
];

$valuation = apaczka_request('order_valuation/', $order);
```

## Utworzenie zamówienia

Payload jest identyczny jak przy wycenie:

```php
$created = apaczka_request('order_send/', $order);
$orderId = $created['order']['id'];
```

## Pobranie etykiety (list przewozowy)

Parametry ścieżki są częścią podpisywanej trasy:

```php
$waybill = apaczka_request('waybill/' . $orderId . '/');

// Dokument to PDF zakodowany w base64.
file_put_contents('label.pdf', base64_decode($waybill['waybill']));
```

## Śledzenie przesyłki

```php
$tracking = apaczka_request('tracking/' . $waybillNumber . '/');

foreach ($tracking['data'] as $event) {
    echo $event['status'] . ' — ' . $event['description']
        . ' (' . $event['updated_at'] . ')' . PHP_EOL;
}
```