Opis API

Nasze API ma dwa fundamentalne wywołania: watermark i deliver. Pierwsze wywołanie inicjuje transakcję w systemie oraz zwraca jej identyfikator, a drugie wywołanie potwierdza transakcję. Po wywołaniu deliver i zakończeniu watermarkowania jest wysyłany do Państwa ping na zdefiniowany w systemie adres URL z informacją o zakończeniu transakcji. Razem z pingiem wysyłane są linki do plików.

Dostarczymy Państwu dwa klucze: prywatny i publiczny do podpisywania zleceń API.

API składa się z następujących metod:

watermark

Watermark inicjuje transakcję kupna pliku. Nie jest ona jeszcze wiążąca dla sklepu, i nie jest raportowana wydawcy. Pozwala to na rozpoczęcie procesu watermarkowania przed wpłynięciem potwierdzenia dokonania płatności przez klienta. Z perspektywy klienta zostaje więc skrócony czas oczekiwania na książkę. Plik zostanie udostępniony sklepowi dopiero po wykonaniu metody deliver (opisanej poniżej), dopiero wtedy też transakcja zostanie zarejestrowana w systemie jako dokonana. Zwracany jest alfanumeryczny identyfikator transakcji.

POST
https://www.elibri.com.pl/watermarking/watermark
Zleca watermark
Trzeba przekazać następujące parametry:
isbn albo record_reference
Należy podać numer isbn książki (bez myślników), albo record_reference produktu - w zależności od nazwy parametru. Zdecydowanie polecamy używanie record reference, Ponieważ wydawcy czasem zmieniają numer ISBN.
formats
Formaty, w jakich ma zostać dostarczony plik (wymienione po przecinku), np. 'epub,mobi'. Może przyjmować wartości: epub, mobi, pdf, mp3_in_zip (pliki mp3 w archiwum zip), mp3_in_lpf (pliki mp3 w archiwum zip + package.json z manifestem)
visible_watermark
Tekst, który ma zostać doklejony na końcu każdego rozdziału
low_priority (opcjonalnie)
Jest to opcjonalny parametr. Jeśli wartość będzie true, to zadanie zostanie dodane do kolejki niskopriorytetowej, obsługiwanej wtedy, gdy główna kolejka jest pusta
price
Jest to opcjonalny parametr, cena netto, po której książka jest kupowana od wydawcy/dystrybutora. Podanie tej ceny ułatwia rozstrzyganie ew. różnic w rozliczeniach.
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig

Podpis zlecenia za pomocą algorytmu HMAC (stamp jest kluczem, secret podpisywaną wartością)

Przykład w ruby:

timestamp = Time.now.to_i
hmac = OpenSSL::HMAC.digest('sha1', timestamp.to_s, self.secret)
sig = CGI.escape(Base64.encode64(hmac).strip)

Przykład w php:

$stamp = time();
$hmac = hash_hmac("sha1", $this->secret, $stamp, true);
$sig = rawurlencode(base64_encode($hmac));
token
Publiczny token dostarczony przez Elibri
supplier (opcjonalnie)
Numeryczny identyfikator wybranego dostawcy pliku w systemie Elibri
client_symbol (opcjonalnie)
Identyfikator zamówienia klienta - opcjonalny alfanumeryczny string zapisywany przy transakcji (maks 255 znaków)
promotion_id (opcjonalnie)
Opcjonalny identyfikator promocji w której sprzedany został plik
low_priority (opcjonalnie)
Jest to opcjonalny parametr. Jeśli wartość będzie true, to zadanie zostanie dodane do kolejki niskopriorytetowej, obsługiwanej wtedy, gdy główna kolejka jest pusta

Zwracane wartości:

Jeśli zlecenie zostało przyjęte, to serwer zwraca status 200, a wysłana odpowiedź to alfanumeryczny identyfikator transakcji (trans_id). W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
403
nie został znaleziony produkt, lub produkt nie jest dostępny (np. nie nastąpiła jeszcze premiera produktu), lub produkt nie posiada żądanego formatu.
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

deliver

Jest to metoda, którą należy wywołać po watermark. Deliver potwierdza transakcję w systemie Elibri, powinna być więc wykonana dopiero po odebraniu płatności od klienta.

W pingu kończącym transakcję dostarczamy jeden lub więcej linków do pliku. Linki mogą zostać bezpośrednio przekazane klientowi, sklep może też ściągnąć pliki i utrzymywać je na swoim serwerze.

Po wygenerowaniu linku lub linków nasz serwer łączy się z przekazanym przez Państwa URL-em (tzw. ping, metoda POST), przekazując w parametrze trans_id identyfikator transakcji, która została ukończona, oraz linki do plików. Przekazane linki są ważne bezterminowo. Więcej informacji o pingu zwrotnym znajdą Państwo tutaj.

Wywołanie deliver może nastąpić w ciągu 10 dni od wywołania metody watermark.

POST
https://www.elibri.com.pl/watermarking/deliver
Potwierdź transakcję i dostarcz plik
Trzeba przekazać następujące parametry
trans_id
Identyfikator transakcji zwrócony przez metodę watermark
low_priority (opcjonalnie)
Jest to opcjonalny parametr. Jeśli wartość będzie true, to zadanie zostanie dodane do kolejki niskopriorytetowej, obsługiwanej wtedy, gdy główna kolejka jest pusta.
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli zlecenie zostało przyjęte, to serwer zwraca status 200 i odpowiedź "OK". W przypadku błędu, zwracane są następujące statusy HTTP:

202
dla transakcji został już wcześniej wywołany deliver
400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny lub parametr sig jest błędny
403
nie została odnaleziona transakcja (błędny trans_id), albo wywołanie następuje po 10 dniach od rejestracji transakcji
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

available_files

Metoda ta zwraca listę produktów dostępnych do watermarkingu.

GET
https://www.elibri.com.pl/watermarking/available_files.format
Trzeba przekazać następujące parametry
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli żądanie zostanie przyjęte, to serwer zwraca status 200, a w treści znajduje się odpowiednio JSON lub XML zawierający informacje o dostępnych do watermarkingu produktach, ich formatach i dostawcach pliku. Przykład w xml:

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <product>
    <record_reference>dfc535dc7f9fc1b0dc51</record_reference>
    <isbn>9788372785831</isbn>
    <title>Uporczywe echo</title>
    <publisher_name>Media Rodzina</publisher_name>
    <publisher_id>16</publisher_id>
    <formats>
      <format>epub</format>
      <format>mobi</format>
    </formats>
    <suppliers>
      <supplier>31</supplier>
    </suppliers>
  </product>
  <product>
    <record_reference>9fec88334cf2983f4459</record_reference>
    <isbn>9788375061215</isbn>
    <title>Rozbitek@brzeg.pl</title>
    <publisher_name>Zysk i S-ka</publisher_name>
    <publisher_id>126</publisher_id>
    <formats>
      <format>epub</format>
      <format>mobi</format>
    </formats>
    <suppliers>
      <supplier>31</supplier>
    </suppliers>
  </product>
</products>

Jako json:

[{
  "title" : "Uporczywe echo",
  "record_reference" : "dfc535dc7f9fc1b0dc51",
  "isbn" : "9788372785831",
  "publisher_id" : 16,
  "publisher_name" : "Media Rodzina",
  "suppliers" : [31],
  "formats" : ["epub","mobi"]
}, {
  "title" : "Rozbitek@brzeg.pl",
  "record_reference" : "9fec88334cf2983f4459",
  "isbn" : "9788375061215",
  "publisher_id" : 126,
  "publisher_name" : "Zysk i S-ka",
  "suppliers" : [31],
  "formats" : ["epub","mobi"]
  }
]

W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

Uwaga! Informacja dotycząca produktu może zawierać tag / klucz "available_until" - oznacza to, że plik jest dostępny do watermarkingu tylko do tej daty i zostanie po niej wyłączony.

soon_available_files

Metoda ta zwraca listę produktów wkrótce dostępnych do watermarkingu.

GET
https://www.elibri.com.pl/watermarking/soon_available_files.format
Trzeba przekazać następujące parametry
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli żądanie zostanie przyjęte, to serwer zwraca status 200, a w treści znajduje się odpowiednio JSON lub XML zawierający informacje o dostępnych do watermarkingu produktach, ich formatach i dostawcach pliku, np.:

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <product>
    <record_reference>7dbeba8100d5b60f10fb</record_reference>
    <isbn>9788366420786</isbn>
    <title>Biała mapa</title>
    <publisher_name>Smak Słowa</publisher_name>
    <publisher_id>286</publisher_id>
    <formats>
      <format>epub</format>
      <format>mobi</format>
    </formats>
    <suppliers>
    </suppliers>
    <available_date>2022-03-16T00:00:00+01:00</available_date>
  </product>
  <product>
    <record_reference>49e11f230fc082d29078</record_reference>
    <isbn>9788381884839</isbn>
    <title>Wirus</title>
    <publisher_name>Rebis</publisher_name>
    <publisher_id>17</publisher_id>
    <formats>
      <format>mp3_in_zip</format>
    </formats>
    <suppliers>
    </suppliers>
    <available_date>2022-03-09T00:00:00+01:00</available_date>
  </product>
</products>

lub jako json:

[{
  "publisher_name" : "Smak Słowa",
  "available_date" : "2022-03-16T00:00:00+01:00",
  "formats" : ["epub", "mobi"],
  "publisher_id" : 286,
  "suppliers" : [],
  "record_reference" : "7dbeba8100d5b60f10fb",
  "title" : "Biała mapa",
  "isbn" : "9788366420786"
}, {
  "suppliers" : [],
  "record_reference" : "49e11f230fc082d29078",
  "title" : "Wirus",
  "isbn" : "9788381884839",
  "formats" : ["mp3_in_zip"],
  "publisher_id" : 17,
  "available_date" : "2022-03-09T00:00:00+01:00",
  "publisher_name" : "Rebis"
 }]

W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

soon_unavailable_files

Metoda ta zwraca listę produktów, które wkrótce przestaną być dostępne do watermarkingu.

GET
https://www.elibri.com.pl/watermarking/soon_unavailable_files.format
Trzeba przekazać następujące parametry
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli żądanie zostanie przyjęte, to serwer zwraca status 200, a w treści znajduje się odpowiednio JSON lub XML zawierający informacje o dostępnych do watermarkingu produktach, ich formatach i dostawcach pliku, a także dacie po której produkt przestanie być dostępny, np.:

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <product>
    <record_reference>c2989c254e0282bf640f</record_reference>
    <isbn>9788378181194</isbn>
    <title>Mossad</title>
    <publisher_name>Rebis</publisher_name>
    <publisher_id>17</publisher_id>
    <formats>
      <format>epub</format>
      <format>mobi</format>
    </formats>
    <suppliers>
      <supplier>31</supplier>
    </suppliers>
    <available_until>2022-03-04T00:00:00+01:00</available_until>
  </product>
</products>

Jako json:

[{
  "publisher_name" : "Rebis",
  "formats" : ["epub", "mobi"],
  "title" : "Mossad",
  "suppliers" : [31],
  "available_until" : "2022-03-04T00:00:00+01:00",
  "publisher_id" : 17,
  "record_reference" : "c2989c254e0282bf640f",
  "isbn" : "9788378181194"
}]

W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

api_complaints

Metoda ta zgłasza reklamację do transakcji watermarkingu. Reklamacje można składać do 10. dnia następnego miesiąca po zakończeniu transakcji w przypadku PDW, w przypadku pozostałych klientów do 5. dni następnego miesiąca. Reklamacja nie jest możliwa jeśli pliki zostały już pobrane.

POST
https://www.elibri.com.pl/api_complaints
Zgłoś reklamację
Trzeba przekazać następujące parametry
trans_id
Identyfikator transakcji do reklamacji
reason
Zgłaszany powód reklamacji
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli żądanie zostanie przyjęte, to serwer zwraca status 200, a w treści znajduje się "OK". W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
403
Nieprawidłowy trans_id (nieistniejący bądź była do niego zgłaszana już wcześniej reklamacja), albo minął termin składania reklamacji
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

api_promotions

Metoda ta pozwala na pobieranie zdefiniowanych w systemie promocji

GET
https://www.elibri.com.pl/api_promotions.format
Pobierz listę zdefiniowanych promocji
W miejscu format proszę podać xml lub json. Trzeba przekazać następujące parametry:
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri

Jeśli żądanie zostanie przyjęte, to serwer zwraca status 200, a w treści znajduje się lista dostępnych promocji. Przykłady odpowiedzi:

<?xml version="1.0" encoding="UTF-8"?>
<promotions>
  <promotion>
    <id>353</id>
    <name>Promocja testowa</name>
    <start_date>2015-02-14</start_date>
    <end_date>2015-02-21</end_date>
    <immutable>false</immutable>
    <system_info>
      <publisher_name>Powergraph</publisher_name>
      <watermarking_client_name>books.pl</watermarking_client_name>
      <watermarking_supplier_id>12</watermarking_supplier_id>
      <watermarking_supplier_name>e-olesiejuk</watermarking_supplier_name>
    </system_info>
  </promotion>
</promotions>

Jako json:

[{
  "id": 353,
  "name": "Promocja testowa",
  "start_date": "2015-02-14",
  "end_date": "2015-02-21",
  "immutable": true,
  "system_info": {
    "publisher_name": "Powergraph",
    "watermarking_client_name": "books.pl",
    "watermarking_supplier_id": 12,
    "watermarking_supplier_name": "e-olesiejuk"
  }
}]

W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)

api_promotion

Pobranie szczegółowych informacji o zdefiniowanej promocji, w tym listy produktów, dla których klient otrzyma dodatkowy rabat.

GET
https://www.elibri.com.pl/api_promotions/:id.format
Pobierz opis promocji
W miejscu format proszę podać xml lub json. Trzeba przekazać następujące parametry:
stamp
Liczba sekund, która upłynęła od 1 stycznia 1970 roku (ruby: Time.now.to_i, php: time())
sig
Podpis zlecenia, obliczany tak samo, jak w przypadku metody watermark
token
Publiczny token dostarczony przez Elibri
id
Numer promocji

Jeśli żądanie zostaie przyjęte, to serwer zwraca status 200, a w treści znajduje się opis promocji. Przykłady odpowiedzi:

<?xml version="1.0" encoding="UTF-8"?>
  <promotion>
    <name>Promocja testowa</name>
    <start_date>2015-02-14</start_date>
    <end_date>2015-02-21</end_date>
    <immutable>false</immutable>
    <system_info>
      <publisher_name>Powergraph</publisher_name>
      <watermarking_client_name>books.pl</watermarking_client_name>
      <watermarking_supplier_id>12</watermarking_supplier_id>
      <watermarking_supplier_name>e-olesiejuk</watermarking_supplier_name>
    </system_info>
    <discount>
      <product>
        <title>Holocaust F</title>
        <ean>9788361187936</ean>
        <record_reference>b055ee0518f79a8fdc73</record_reference>
      </product>
      <arbitral>false</arbitral>
      <cascade>true</cascade>
      <discount_percent>14.0</discount_percent>
    </discount>
    <discount>
      <product>
        <title>Nowi Ludzie</title>
        <ean>9788361187950</ean>
        <record_reference>2dd03f12ed56a67a57e0</record_reference>
      </product>
      <arbitral>false</arbitral>
      <cascade>true</cascade>
      <discount_percent>14.0</discount_percent>
    </discount>
    <discount>
      <product>
        <title>Rok po końcu świata</title>
        <ean>9788361187981</ean>
        <record_reference>0a684fce54fbc1c8a603</record_reference>
      </product>
      <arbitral>false</arbitral>
      <cascade>true</cascade>
      <discount_percent>14.0</discount_percent>
    </discount>
  </promotion>

Jako json:

{
    "name": "Promocja testowa",
    "start_date": "2015-02-14",
    "end_date": "2015-02-21",
    "immutable": false,
    "system_info": {
      "publisher_name": "Powergraph",
      "watermarking_client_name": "books.pl",
      "watermarking_supplier_id": 12,
      "watermarking_supplier_name": "e-olesiejuk"
    },
    "discount": [
      {
        "product": {
          "title": "Holocaust F",
          "ean": "9788361187936",
          "record_reference": "b055ee0518f79a8fdc73"
        },
        "arbitral": false,
        "cascade": true,
        "discount_percent": "14.0"
      },
      {
        "product": {
          "title": "Nowi Ludzie",
          "ean": "9788361187950",
          "record_reference": "2dd03f12ed56a67a57e0"
        },
        "arbitral": false,
        "cascade": true,
        "discount_percent": "14.0"
      },
      {
        "product": {
          "title": "Rok po końcu świata",
          "ean": "9788361187981",
          "record_reference": "0a684fce54fbc1c8a603"
        },
        "arbitral": false,
        "cascade": true,
        "discount_percent": "14.0"
      }
    ]
  }

W przypadku błędu, zwracane są następujące statusy HTTP:

400
zostały podane błędne parametry
401
został podany nieprawidłowy token publiczny, lub parametr sig jest błędny
408
parametr stamp jest błędny (różnica większa, niż 60 sekund)
404
promocja o danym id nie została znaleziona

Masz pyta­nia? Chcesz nawią­zać współ­pracę?

Skon­tak­tuj się z nami!

Znamy się na auto­ma­ty­za­cji i opty­ma­li­za­cji pro­ce­sów wydaw­ni­czych.
Przy­go­to­wu­jemy roz­wią­za­nia dla kon­kret­nego wydaw­nic­twa.
Co możemy dla Cie­bie zro­bić? Napisz do nas: kon­takt@eli­bri.com.pl