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.
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));
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:
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.
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:
available_files
Metoda ta zwraca listę produktów dostępnych do watermarkingu.
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:
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.
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:
soon_unavailable_files
Metoda ta zwraca listę produktów, które wkrótce przestaną być dostępne do watermarkingu.
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:
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.
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:
api_promotions
Metoda ta pozwala na pobieranie zdefiniowanych w systemie promocji
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:
api_promotion
Pobranie szczegółowych informacji o zdefiniowanej promocji, w tym listy produktów, dla których klient otrzyma dodatkowy rabat.
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: