Wprowadzenie

elibri jest systemem stworzonym dla wydawnictw, które mogą za jego pośrednictwem sprzedawać swoje ebooki na swoich stronach internetowych, jak i na stronach współpracujących firm. Pełna dokumentacja API znajduje się pod adresem https://www.elibri.com.pl/doc/watermarking/

Instalacja

Bibliotekę instalujemy przez Composera:

composer require elibri/watermarking-client

Wymagane jest PHP 7.4 lub nowsze oraz rozszerzenia curl i json. Źródła: https://github.com/elibri/elibriWatermarkingPHP

Aktualizacja do wersji 1.0

Wersja 1.0 nie jest zgodna wstecz z serią 0.x:

Biblioteka jest instalowana Composerem i ładowana przez PSR-4; nie ma już kanału PEAR ani pliku elibriWatermarkingPHP.php, który trzeba było ręcznie wymagać.
Klasy mają przestrzenie nazw: ElibriWatermarkingClient to teraz Elibri\Watermarking\WatermarkingClient.
Wyjątki przeniesiono do Elibri\Watermarking\Exception\ i pozbawiono przedrostka Elibri. Wszystkie dziedziczą po ElibriException.
Nazwy metod są w camelCase: available_files to availableFiles, soon_available_files to soonAvailableFiles, soon_unavailable_files to soonUnavailableFiles.
Certyfikaty TLS są weryfikowane, a żądania mają timeout.

Wcześniej, 18.09.2024, z metody watermark zostały usunięte parametry $title_postfix oraz $client_id, a metoda retry została wycofana.

Użycie biblioteki

Poprzez API zlecasz watermarking książki, podając jej identyfikator (ISBN lub record reference), formaty (tablica stałych Format lub lista po przecinku, na ogół 'epub,mobi') oraz widoczny watermark, który jest umieszczany na końcu każdego rozdziału.

Link do zwatermarkowanego pliku jest wysyłany razem z pingiem informującym o zakończeniu transakcji, więcej informacji: https://www.elibri.com.pl/doc/watermarking/ping

Niezbędne jest podpisanie umów z wydawnictwami, których pliki mają być sprzedawane za pośrednictwem systemu elibri.

API watermarkingu jest maksymalnie proste, składa się z dwóch podstawowych wywołań: watermark oraz deliver. Metody te są oferowane przez klasę WatermarkingClient.

watermark

Sugerujemy, żeby zlecenie watermarkingu książki odbyło się jak najwcześniej, żeby klient jak najkrócej czekał na dostarczenie pliku. Wysłanie zlecenia watermarkingu nie rejestruje transakcji w systemie, można więc je wysłać w momencie, kiedy klient opuszcza koszyk i przechodzi do płacenia. Zwatermarkowany plik jest udostępniany sklepowi dopiero po wykonaniu metody deliver.

deliver

Deliver skutkuje zarejestrowaniem transakcji w systemie oraz dostarczeniem pliku. Sklep powinien na tym etapie mieć potwierdzenie dokonania płatności, ponieważ wydawnictwo obarczy go fakturą za dokonaną transakcję.

Może się zdarzyć, że sklep zleci watermarkowanie, a nie wywoła metody deliver, bo klient nie dokonał płatności. W takiej sytuacji transakcja zostaje anulowana i żadna ze stron nie zostanie obciążona. Wywołanie deliver musi nastąpić w ciągu 7 dni od wywołania watermark.

Po zakończeniu znakowania pliku nasz serwer łączy się z przekazanym przez Państwa URL-em (metoda POST), przekazując w parametrze trans_id identyfikator transakcji, która została ukończona. W pingu zwrotnym umieszczany jest również link do pliku, który mogą Państwo udostępnić klientom.

Lista dostępnych produktów

Można również pobrać listę dostępnych plików dla założonego klienta (uwzględnia ona przypisanych wydawców oraz daty premier). Uwzględnia również książki, dla których wgrane są wszystkie pliki, ale nie nastąpiła jeszcze premiera - wtedy ustawione jest pole available_date. Służy do tego metoda WatermarkingClient::availableFiles.

Obsługa błędów

Każdy wyjątek rzucany przez bibliotekę dziedziczy po ElibriException, wystarczy więc przechwycić tę jedną klasę.

Przykłady

Zlecenie watermarkingu

<?php
 
declare(strict_types=1);
 
use Elibri\Watermarking\Exception\ElibriException;
use Elibri\Watermarking\Format;
use Elibri\Watermarking\WatermarkingClient;
 
require_once __DIR__ . '/../vendor/autoload.php';
 
// Dostępy do API elibri.
$token = '061df0c87cd0472a5e4e5708fd788246';
$secret = 'fbef4d3bbb30cbf502bbdb0f8ede3fc7';
 
$bookRecordReference = '2a0ec1239e285ec46b11';
 
$client = new WatermarkingClient($token, $secret);
 
try {
    // Zleć watermarkowanie - jak najwcześniej, np. gdy klient opuszcza koszyk.
    $transId = $client->watermark(
        $bookRecordReference,
        [Format::EPUB, Format::MOBI],
        'Książka dla Wojtka Kowalskiego'
    );
    echo "transid: $transId\n";
 
    // Potwierdź transakcję - dopiero po zarejestrowaniu płatności.
    echo $client->deliver($transId), "\n";
 
    // Teraz czekaj na callback od elibri na zdefiniowany adres;
    // w callbacku znajdziesz linki do zwatermarkowanych plików.
} catch (ElibriException $e) {
    fwrite(STDERR, 'Błąd API elibri: ' . $e->getMessage() . "\n");
    exit(1);
}

Lista dostępnych plików

<?php
 
declare(strict_types=1);
 
use Elibri\Watermarking\Exception\ElibriException;
use Elibri\Watermarking\WatermarkingClient;
 
require_once __DIR__ . '/../vendor/autoload.php';
 
$client = new WatermarkingClient(
    '061df0c87cd0472a5e4e5708fd788246',
    'fbef4d3bbb30cbf502bbdb0f8ede3fc7'
);
 
try {
    foreach ($client->availableFiles() as $book) {
        printf(
            "%s - %s%s\n",
            $book['record_reference'] ?? '?',
            $book['title'] ?? '?',
            isset($book['available_date']) ? ' (premiera: ' . $book['available_date'] . ')' : ''
        );
    }
} catch (ElibriException $e) {
    fwrite(STDERR, 'Błąd API elibri: ' . $e->getMessage() . "\n");
    exit(1);
}