Copy page

Pierwsze kroki

SDK PHP

AlsendoOne SDK to oficjalny klient PHP dla Apaczka API v2 i zalecany sposób integracji — obsługuje podpisywanie żądań, znaczniki expires i mapowanie błędów, a każdą metodę API udostępnia przez typowane obiekty żądań i odpowiedzi.

• Źródła: github.com/Alsendo/AlsendoOneSDK (MIT)
• Pakiet: alsendo/alsendo-one-sdk na Packagist
• Wymaga PHP ≥ 7.4 oraz ext-json

Instalacja

Code
composer require alsendo/alsendo-one-sdk

SDK zawiera domyślny adapter Guzzle — zainstaluj Guzzle obok niego (albo użyj własnego klienta HTTP):

Code
composer require guzzlehttp/guzzle guzzlehttp/psr7

Pierwsze kroki

Uzyskaj app_id i app_secret w panelu Apaczka w sekcji Ustawienia → API, a następnie:

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

use AlsendoOne\SDK\AlsendoClient;

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

// Pobierz usługi dostępne na Twoim koncie
$structure = $client->getServiceStructure();

foreach ($structure->getServices() as $service) {
    echo $service['name'] . ' (ID: ' . $service['service_id'] . ')' . PHP_EOL;
}

Uwierzytelnianie jest w pełni automatyczne — SDK wylicza podpis HMAC-SHA256 oraz znacznik expires dla każdego żądania.

Każde żądanie niesie też nagłówek User-Agent: AlsendoOneSDK/<wersja> PHP/<wersja>, dzięki któremu Apaczka wie, na jakim wydaniu SDK działa Twoja integracja — zachowaj ten nagłówek, jeśli podstawiasz własny klient HTTP.

Dostępne metody

Metoda	Opis
getServiceStructure()	Dostępne usługi, opcje, typy paczek i odbiorów
getPoints($supplier, $countryCode, $subtype)	Punkty nadania/odbioru przewoźnika (np. Paczkomaty InPost)
getValuation($orderData)	Wycena — ceny zwracane w groszach (1 PLN = 100 gr)
sendOrder($orderData)	Utworzenie zamówienia przesyłki
getOrder($orderId) / getOrders($page, $limit)	Szczegóły zamówienia / lista z paginacją (max 25 na stronę)
cancelOrder($orderId)	Anulowanie zamówienia
getPickupHours($postalCode, $service)	Dostępne okna odbioru kurierskiego dla kodu pocztowego
schedulePickup(...) / scheduleBatchPickup(...)	Zamówienie odbioru kurierskiego dla jednego / wielu zamówień
getTracking($waybillNumber)	Zdarzenia śledzenia dla listu przewozowego
getWaybill($orderId)	Etykieta jako PDF zakodowany w base64
getTurnIn($orderIds)	Zbiorcze potwierdzenie nadania (PDF)
getDispatchCode($orderId)	Kod nadania/zwrotu przewoźnika
request($route, $params)	Surowe podpisane żądanie do dowolnego endpointu

Aplikacje partnerskie z podwyższonymi uprawnieniami mają dodatkowo registerCustomer() oraz checkData() (walidacja NIP, limit 100 wywołań dziennie).

Żądania można budować jako zwykłe tablice (zgodne z payloadami z referencji API) albo typowanymi builderami — OrderRequest, Address, ShipmentRequest, PickupRequest itd. Pełny przykład znajdziesz w cyklu życia zamówienia.

Obsługa błędów

Wszystkie wyjątki SDK dziedziczą po AlsendoOne\SDK\Exception\AlsendoException:

Wyjątek	Znaczenie
ApiException	API zwróciło kopertę błędu — zobacz semantykę błędów
ConnectionException	Samo żądanie HTTP nie powiodło się (timeout, DNS, status HTTP inny niż 200)
WebhookVerificationException	Przychodzący webhook push tracking nie przeszedł weryfikacji podpisu

Code
use AlsendoOne\SDK\Exception\ApiException;
use AlsendoOne\SDK\Exception\ConnectionException;

try {
    $order = $client->getOrder(123456);
} catch (ApiException $e) {
    // np. "Order not found." — pełna koperta przez $e->getResponseData()
    echo 'API error ' . $e->getCode() . ': ' . $e->getMessage();
} catch (ConnectionException $e) {
    echo 'Connection error: ' . $e->getMessage();
}

API nie rozróżnia błędów uwierzytelniania i walidacji kodem statusu (w praktyce zawsze 400) — gdy musisz je odróżnić, sprawdzaj treść komunikatu wyjątku.

Własny klient HTTP, retry i logowanie

Dowolny klient HTTP może zastąpić wbudowany adapter Guzzle — wystarczy zaimplementować HttpClientInterface. Dwa opcjonalne dekoratory opakowują dowolną implementację:

Code
use AlsendoOne\SDK\Http\GuzzleHttpClient;
use AlsendoOne\SDK\Http\LoggingHttpClient;
use AlsendoOne\SDK\Http\RetryingHttpClient;

$httpClient = new LoggingHttpClient(
    new RetryingHttpClient(new GuzzleHttpClient(), maxRetries: 2, delayMs: 500),
    $psrLogger
);

$client = new AlsendoClient('app_id', 'app_secret', $httpClient);

RetryingHttpClient ponawia wyłącznie błędy sieciowe, nigdy koperty błędów API — pamiętaj też, że błąd sieciowy nie gwarantuje, że żądanie nie dotarło do serwera; ponawianie operacji nieidempotentnych, takich jak sendOrder(), może utworzyć zduplikowane zamówienia. LoggingHttpClient loguje URL, statusy i czas trwania przez dowolny logger PSR-3 i nigdy nie loguje danych dostępowych ani podpisanych payloadów.

Sandbox

Przekaż AlsendoClient::SANDBOX_URL jako bazowy URL, aby testować w środowisku sandbox — zobacz Testowanie integracji:

Code
$client = new AlsendoClient(
    'app_id',
    'app_secret',
    null,                        // domyślny klient Guzzle
    AlsendoClient::SANDBOX_URL
);

Integrujesz z innego języka?

SDK jest tylko dla PHP. Z każdego innego języka wywołuj API bezpośrednio — cały kontrakt to podpisany POST z kopertą, opisany w Podpisywaniu żądań (HMAC), z przykładami cURL do skopiowania w przykładach implementacji.