API Plaza dla systemów online.
: 2015-11-28, 12:08
Dotyczy komunikacji systemów zewnętrznych z Plaza 2022, Plaza WEB
Może być używany przez zewnętrzne systemy rezerwacyjne.
Użytkownik musi mieć login, hasło, uprawnienie do korzystania z api R_API = 1, musi mieć nadany klucz publiczny API_KEY varchar (100) i klucz prywatny API_SKEY varchar(100). Klucz prywatny jak i publiczny muszą być niepowtarzalne w obrębie bazy i są to randomowe stringi [a-zA-Z0-9].
Autoryzacja użytkownika
POST /api/v1/auth/{connection?}
Atrybut "connection" nie jest wymagany w przypadku obsługi tylko jednej bazy danych. Gdy baz jest więcej, jak w przypadku sieci hoteli, trzeba podać w tym miejscu nazwę połączenia zdefiniowaną w pliku /app/config/database.php, w przeciwnym razie zostanie użyte połączenie domyślne.
W poście trzeba podać login, hasło i klucz publiczny np. login=login&password=password&api_key=api_key
W odpowiedzi zostanie odesłany token, który musi być przekazany w kolejnym żądaniu lub komunikat o błędzie.
Czas ważności tokenu to 3 sekundy.
Przykładowe odpowiedzi:
Sprawdzanie dostępności - wymagana autoryzacja
GET /api/v1/availability
Do powyższego trzeba dokleić informację o tokenie (wymagane) dacie początkowej (wymagane, format Y-m-d), dacie końcowej(wymagane, format Y-m-d) i typie pokoju (opcjonalne, integer). Przykładowe wywołania:
W odpowiedzi zostanie zwrócona lista typów pokoi z ilością wolnych pokoi na każdą datę w podanym zakresie lub komunikat o błędzie.
W odpowiedzi zostanie zwrócona lista z ilością wolnych pokoi na każdą datę w podanym zakresie dla podanego typu lub komunikat o błędzie.
Przykładowa odpowiedź:
Zapis rezerwacji - wymagana autoryzacja
POST api/v1/reservation
Atrybuty:
dane rezerwacji
number - wymagany, zewnętrzny numer rezerwacji, string (30)
checkin - wymagany, data rozpoczęcia pobytu, format Y-m-d
checkout - wymagany, data zakończenia pobytu, format Y-m-d
roomtype - wymagany, typ pokoju, string
res_date - wymagany, data rezerwacji, format Y-m-d
adults - opcjonalny, ilość dorosłych, integer
children - opcjonalny, ilość dzieci, integer
addition - opcjonalny, ilość dodatkowych osób np. dostawek, integer
price - wymagany, cena za dobę w PLN, numeric (15,2)
price_eur - opcjonalny, cena za dobę w euro, numeric (15,2)
total - wymagany, całkowita cena pobytu w PLN, numeric (15,2)
total_eur - opcjonalny, całkowita cena pobytu w euro, numeric (15,2)
advance - wymagany, wpłacona/wymagana zaliczka w PLN, numeric (15,2)
advance_eur - opcjonalny, wpłacona/wymagana zaliczka w euro, numeric (15,2)
comments - opcjonalny, uwagi, string (250)
dane osoby rezerwującej
surname - wymagany, nazwisko, string (50)
name - wymagany, imię/imiona, string (50)
email - wymagany, email, string (250)
phone - wymagany, telefon, string (30)
pesel - opcjonalny, pesel, string (11)
city - opcjonalny, miejscowość, string (50)
street - opcjonalny, ulica, string (50)
house - opcjonalny, numer domu, string (10)
local - opcjonalny, numer mieszkania, string (10)
postal_code - opcjonalny, kod pocztowy, string (10)
postal_city - opcjonalny, poczta, string (50)
dane do faktury
f_name - opcjonalny, nazwa firmy, string (50)
f_email - opcjonalny, email, string (250)
f_phone - opcjonalny, telefon, string (30)
f_nip - opcjonalny, nip, string (13)
f_city - opcjonalny, miejscowość, string (50)
f_street - opcjonalny, ulica, string (50)
f_house - opcjonalny, nr domu, string (10)
f_local - opcjonalny, nr mieszkania, string (10)
f_postal_code - opcjonalny, kod pocztowy, string (10)
f_postal_city - opcjonalny, poczta, string (50)
W odpowiedzi zostanie odesłany komunikat o statusie (201, 304).
Przykładowe odpowiedzi:
Testy
Testowa odpowiedź dla api bez podania pokoju:
Czas odpowiedzi:
podtypy pokoi - ok 70 sekund dla wszystkich (w testowej bazie - 45) podtypów pokoi i dostępności na miesiąc.
Testowa odpowiedź dla api z podaniem pokoju:
Czas odpowiedzi:
podtypy pokoi - ok 2 sekundy dla jednego podtypu pokoju i dostępności na miesiąc, dla dostępności na cały rok czas odpowiedzi to ok 22 sekundy.
Im więcej typów/podtypów pokoi tym czas odpowiedzi będzie dłuższy.
Zapis rezerwacji - wymagana autoryzacja
POST api/v1/reservation
W odpowiedzi zostanie odesłany komunikat o statusie (201, 401, 404, 500).
Komunikat zwrotny po zapisie rezerwacji:
Zmiany rezerwacji - wymagana autoryzacja
PUT api/v1/reservation
Atrybuty:
number - wymagany, zewnętrzny numer rezerwacji, string (30)
canceled - wymagany, integer (0, gdy aktywna lub 1, gdy anulowana)
comments - opcjonalny, uwagi, string (250)
W odpowiedzi zostanie odesłany komunikat o statusie (201, 401, 404, 500).
Przykładowe odpowiedzi:
Lista pokoi - wymagana autoryzacja
Podaje listę pokoi gościnnych w obiekcie razem ze statusami i numerami zamków
GET /api/v1/roomlist
Do powyższego trzeba dokleić informację o tokenie (wymagane)
Przykładowe wywołanie:
Lista rezerwacji- wymagana autoryzacja
Podaje listę rezerwacji w obiekcie razem ze statusami i numerami zamków
GET /api/v1/reservationlist
Do powyższego trzeba dodać informację o tokenie (wymagane)
dacie początkowej (wymagane, format Y-m-d), dacie końcowej(wymagane, format Y-m-d) i numerze rezerwacji (opcjonalne, integer).
Przykładowe wywołania:
Checkin - wymagana autoryzacja
Informacja o zameldowaniu gościa z systemu zewnętrznego
POST api/v1/checkin
Do powyższego trzeba dodać informację o tokenie (wymagane)
numerze rezerwacji (wymagane, integer).
W odpowiedzi zostanie odesłany komunikat o statusie (0, 1, 201, 401, 404, 500).
Komunikat zwrotny po zapisie pobytu:
Może być używany przez zewnętrzne systemy rezerwacyjne.
Użytkownik musi mieć login, hasło, uprawnienie do korzystania z api R_API = 1, musi mieć nadany klucz publiczny API_KEY varchar (100) i klucz prywatny API_SKEY varchar(100). Klucz prywatny jak i publiczny muszą być niepowtarzalne w obrębie bazy i są to randomowe stringi [a-zA-Z0-9].
Autoryzacja użytkownika
POST /api/v1/auth/{connection?}
Atrybut "connection" nie jest wymagany w przypadku obsługi tylko jednej bazy danych. Gdy baz jest więcej, jak w przypadku sieci hoteli, trzeba podać w tym miejscu nazwę połączenia zdefiniowaną w pliku /app/config/database.php, w przeciwnym razie zostanie użyte połączenie domyślne.
W poście trzeba podać login, hasło i klucz publiczny np. login=login&password=password&api_key=api_key
W odpowiedzi zostanie odesłany token, który musi być przekazany w kolejnym żądaniu lub komunikat o błędzie.
Czas ważności tokenu to 3 sekundy.
Przykładowe odpowiedzi:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>200</code>
<token>asdfdsgsdfgfgf15665gsdfg156fgSFDGfv56dfvsdf6ds</token>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>401</code>
<message>Username is required</message>
</response>GET /api/v1/availability
Do powyższego trzeba dokleić informację o tokenie (wymagane) dacie początkowej (wymagane, format Y-m-d), dacie końcowej(wymagane, format Y-m-d) i typie pokoju (opcjonalne, integer). Przykładowe wywołania:
Kod: Zaznacz cały
/api/v1/availability?token=token&checkin=Y-m-d&checkout=Y-m-dKod: Zaznacz cały
/api/v1/availability?token=token&checkin=Y-m-d&checkout=Y-m-d&roomtype=zzzPrzykładowa odpowiedź:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>200</code>
<availability>
<room id="5654" date="2015-03-15" quantity="2"/>
<room id="5654" date="2015-03-16" quantity="0"/>
<room id="5654" date="2015-03-17" quantity="5"/>
<room id="5654" date="2015-03-18" quantity="4"/>
<room id="4523" date="2015-03-15" quantity="3"/>
<room id="4523" date="2015-03-16" quantity="6"/>
<room id="4523" date="2015-03-17" quantity="9"/>
<room id="4523" date="2015-03-18" quantity="0"/>
</availability>
</response>
POST api/v1/reservation
Atrybuty:
dane rezerwacji
number - wymagany, zewnętrzny numer rezerwacji, string (30)
checkin - wymagany, data rozpoczęcia pobytu, format Y-m-d
checkout - wymagany, data zakończenia pobytu, format Y-m-d
roomtype - wymagany, typ pokoju, string
res_date - wymagany, data rezerwacji, format Y-m-d
adults - opcjonalny, ilość dorosłych, integer
children - opcjonalny, ilość dzieci, integer
addition - opcjonalny, ilość dodatkowych osób np. dostawek, integer
price - wymagany, cena za dobę w PLN, numeric (15,2)
price_eur - opcjonalny, cena za dobę w euro, numeric (15,2)
total - wymagany, całkowita cena pobytu w PLN, numeric (15,2)
total_eur - opcjonalny, całkowita cena pobytu w euro, numeric (15,2)
advance - wymagany, wpłacona/wymagana zaliczka w PLN, numeric (15,2)
advance_eur - opcjonalny, wpłacona/wymagana zaliczka w euro, numeric (15,2)
comments - opcjonalny, uwagi, string (250)
dane osoby rezerwującej
surname - wymagany, nazwisko, string (50)
name - wymagany, imię/imiona, string (50)
email - wymagany, email, string (250)
phone - wymagany, telefon, string (30)
pesel - opcjonalny, pesel, string (11)
city - opcjonalny, miejscowość, string (50)
street - opcjonalny, ulica, string (50)
house - opcjonalny, numer domu, string (10)
local - opcjonalny, numer mieszkania, string (10)
postal_code - opcjonalny, kod pocztowy, string (10)
postal_city - opcjonalny, poczta, string (50)
dane do faktury
f_name - opcjonalny, nazwa firmy, string (50)
f_email - opcjonalny, email, string (250)
f_phone - opcjonalny, telefon, string (30)
f_nip - opcjonalny, nip, string (13)
f_city - opcjonalny, miejscowość, string (50)
f_street - opcjonalny, ulica, string (50)
f_house - opcjonalny, nr domu, string (10)
f_local - opcjonalny, nr mieszkania, string (10)
f_postal_code - opcjonalny, kod pocztowy, string (10)
f_postal_city - opcjonalny, poczta, string (50)
W odpowiedzi zostanie odesłany komunikat o statusie (201, 304).
Przykładowe odpowiedzi:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>201</code>
<message>Reservation created</message>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>304</code>
<message>Reservation not created</message>
</response>
Testowa odpowiedź dla api bez podania pokoju:
Kod: Zaznacz cały
https://adres:11017/api/v1/test-avail?checkin=2015-11-27&checkout=2015-12-26podtypy pokoi - ok 70 sekund dla wszystkich (w testowej bazie - 45) podtypów pokoi i dostępności na miesiąc.
Testowa odpowiedź dla api z podaniem pokoju:
Kod: Zaznacz cały
https://adres:11017/api/v1/test-avail?checkin=2015-11-27&checkout=2015-12-26&roomtype=19550podtypy pokoi - ok 2 sekundy dla jednego podtypu pokoju i dostępności na miesiąc, dla dostępności na cały rok czas odpowiedzi to ok 22 sekundy.
Im więcej typów/podtypów pokoi tym czas odpowiedzi będzie dłuższy.
Zapis rezerwacji - wymagana autoryzacja
POST api/v1/reservation
W odpowiedzi zostanie odesłany komunikat o statusie (201, 401, 404, 500).
Komunikat zwrotny po zapisie rezerwacji:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>201</code>
<message>Reservation created</message>
<resId>1111</resId>
</response>PUT api/v1/reservation
Atrybuty:
number - wymagany, zewnętrzny numer rezerwacji, string (30)
canceled - wymagany, integer (0, gdy aktywna lub 1, gdy anulowana)
comments - opcjonalny, uwagi, string (250)
W odpowiedzi zostanie odesłany komunikat o statusie (201, 401, 404, 500).
Przykładowe odpowiedzi:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>201</code>
<message>Reservation updated</message>
<resId>1111</resId>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>500</code>
<message>Reservation not updated</message>
</response>Podaje listę pokoi gościnnych w obiekcie razem ze statusami i numerami zamków
GET /api/v1/roomlist
Do powyższego trzeba dokleić informację o tokenie (wymagane)
Przykładowe wywołanie:
Kod: Zaznacz cały
/api/v1/roomlist?token=tokenKod: Zaznacz cały
<?xml version="1.0" encoding="utf-8"?>
<response>
<code>1</code>
<data>
<rooms>
<room>
<id>1</id>
<name>21</name>
<type>DBL</type>
<lock>1000021</lock>
<state>brudny</state>
</room>
</rooms>
</data>
</response>
Lista rezerwacji- wymagana autoryzacja
Podaje listę rezerwacji w obiekcie razem ze statusami i numerami zamków
GET /api/v1/reservationlist
Do powyższego trzeba dodać informację o tokenie (wymagane)
dacie początkowej (wymagane, format Y-m-d), dacie końcowej(wymagane, format Y-m-d) i numerze rezerwacji (opcjonalne, integer).
Przykładowe wywołania:
Kod: Zaznacz cały
/api/v1/reservationlist?token=token&checkin=Y-m-d&checkout=Y-m-d&reservationid=1Kod: Zaznacz cały
<?xml version="1.0" encoding="utf-8"?>
<response>
<code>1</code>
<data>
<reservations>
<reservation>
<id>1</id>
<roomid>1</roomid>
<checkin>2018-08-01</checkin>
<checkout>2018-08-03</checkout>
<surname>Kowalski</surname>
<name>Kowalski</name>
<adults>2</adults>
<children>0</children>
<addition>0</addition>
<email>kowalski@jan.pl</email>
<phone>kowalski@jan.pl</phone>
<state>potwierdzona</state>
<total>1000</total>
<AmountToPay>200</AmountToPay>
</reservation>
</reservations>
</data>
</response>
Checkin - wymagana autoryzacja
Informacja o zameldowaniu gościa z systemu zewnętrznego
POST api/v1/checkin
Do powyższego trzeba dodać informację o tokenie (wymagane)
numerze rezerwacji (wymagane, integer).
Kod: Zaznacz cały
/api/v1/checkin?token=token&reservationid=1Komunikat zwrotny po zapisie pobytu:
Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>201</code>
<message>Checkin success</message>
<StayId>1111</StayId>
</response>