Integracja pliku danych z ofertami

Oferty

Integracja ofert umożliwia przekazywanie strukturalnych informacji o promocjach i rabatach sprzedawcy stosowanych do konkretnych usług w określonych godzinach. Oferty składają się z rzeczywistej oferty (procent zniżki, kwota zniżki…), okresów ważności (określone godziny, dni tygodnia…) i odpowiednich zastosowań (ofertę można wykorzystać tylko w przypadku niektórych usług), a także złożonych kombinacji ograniczeń.

Przykłady ofert:

• 50% zniżki na przystawki w środy i czwartki w grudniu w godzinach 12:00–17:00
• Kup jeden deser i otrzymaj drugi bezpłatnie podczas kolacji z okazji Dnia Matki w godzinach 18:00–22:00
• 5 USD zniżki na danie główne w ramach brunchu w każdą niedzielę od 10:00 do 14:00
• 10% zniżki dla klientów bez rezerwacji, którą można połączyć z 5% zniżki dla subskrybentów premium i 5% zniżki, jeśli użytkownik płaci przez aplikację.

Aby oferta mogła zostać uwzględniona w integracji, musi pasować do modelu danych technicznych i spełniać nasze wymagania. Zapoznaj się z naszymi zasadami dotyczącymi ofert, aby upewnić się, że integracja jest zgodna z zasadami, i dowiedzieć się, co zrobić z ofertami, które nie spełniają wymagań technicznych.

Oferuje implementację

Integracja ofert obejmuje 2 pliki danych, które będą przesyłane codziennie lub z częstotliwością zapewniającą wysoką dokładność (co oznacza, że dane nie będą nieaktualne):

• Możesz:
  • Plik danych sprzedawców (z użyciem konfiguracji Merchant)
  • lub Plik danych o podmiotach (przy użyciu konfiguracji Generic)
• Oraz Plik danych o ofertach (przy użyciu konfiguracji Generic)

Nazwa pola	Typ	Wymaganie	Opis
data	tablica obiektów (Offer)

Nazwa pola	Typ	Wymaganie	Opis
offer_id	tekst	Wymagane	Unikalny identyfikator oferty. Wymagane.
entity_ids	tablica ciągów znaków		Lista sprzedawców, którzy uczestniczą w tej ofercie.
add_on_offer_applicable_to_all_entities	wartość logiczna		Jeśli ma wartość „true”, ta oferta dotyczy wszystkich podmiotów w agregatorze. Dotyczy tylko ofert dodatkowych.
offer_source	enum (OfferSource)	Wymagane	Oferta może być dostarczana przez agregatora, pojedynczego sprzedawcę, a nawet osobę trzecią jako dodatek. Wymagane.
action_type	enum (ActionType)	Wymagane	Usługa, która udostępnia ofertę. Identyfikator offer_id może należeć tylko do jednego typu action_type. Jeśli ofertę można udostępniać w ramach wielu typów usług, należy utworzyć duplikaty ofert z unikalnymi identyfikatorami dla każdego typu usługi. Wymagane.
offer_modes	tablica typu enum (OfferMode)	Wymagane	Metody, za pomocą których można skorzystać z oferty – wizyta bez rezerwacji, rezerwacja, online itp. Wymagane.
offer_category	enum (OfferCategory)	Wymagane	Kategoria oferty. Wymagane.
source_assigned_priority	liczba		Nieujemna liczba całkowita ([1–100], gdzie 1 oznacza najwyższy priorytet) wskazująca poziom priorytetu oferty przypisany przez źródło. Jeśli dla tego samego sprzedawcy dostępnych jest kilka ofert, będzie to sygnał do rankingu ofert. Wartość 0 oznacza, że priorytet nie jest ustawiony.
offer_details	object (OfferDetails)	Wymagane	Szczegóły oferty, takie jak rabat, koszt rezerwacji itp. Wymagane.
offer_restrictions	obiekt (OfferRestrictions)	Wymagane	Opisuje ograniczenia oferty, np. czy wymagana jest subskrypcja lub instrument płatniczy, czy można ją łączyć z innymi ofertami (i jakiego typu) itp. Wymagane.
coupon	obiekt (Coupon)		Szczegóły kuponu. Wymagany w przypadku offer_category: OFFER_CATEGORY_ADD_ON_COUPON_OFFER.
payment_instrument	obiekt (PaymentInstrument)		Szczegóły instrumentu płatniczego. Wymagane w przypadku offer_category: OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.
subscription	obiekt (Subscription)		Szczegóły subskrypcji. Wymagane w przypadku offer_category: OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER.
terms	obiekt (Terms)	Wymagane	Warunki oferty. Wymagane.
validity_periods	tablica obiektów (ValidityPeriod)	Wymagane	Okres ważności oferty. Określa okres ważności oferty, w tym godziny rozpoczęcia i zakończenia, dni tygodnia itp. Wymagane.
offer_url	tekst		Adres URL strony z ofertą sprzedawcy. Wymagane w przypadku offer_category: OFFER_CATEGORY_BASE_OFFER.
tags	tablica typu enum (OfferTag)		Tagi specjalne powiązane z ofertą. Służy do identyfikowania ofert specjalnych, takich jak „Świąteczne”, „Najwyżej oceniane”, „Najczęściej rezerwowane” itp.
brand_id	tekst		Określa markę powiązaną z ofertą. Jeśli nie zostanie ustawiona, używana jest domyślna marka.
availability_level	enum (AvailabilityLevel)		Poziom dostępności oferty.

Nazwa pola	Typ	Wymaganie	Opis
offer_display_text	tekst	Wymagane	Tekst oferty, który dostawca oferty chce wyświetlać klientom na stronie wyników wyszukiwania. Pamiętaj, że może to nie być dokładnie to, co jest wyświetlane użytkownikom, i możemy używać innych metadanych do ponownego napisania lub przeformułowania tych informacji. Wymagane.
	oneOf (offer_specification)	Wymagane	Można ustawić tylko jedno z pól w tym elemencie oneOf.
max_discount_value	object (Money)		Maksymalny rabat, jaki można uzyskać. Na przykład: rabat 10% do 100 PLN.
min_spend_value	object (Money)		Minimalna kwota do zapłaty, która kwalifikuje do skorzystania ze zniżki. Na przykład 10% zniżki, gdy łączna cena wynosi co najmniej 100 PLN.
booking_cost	obiekt (Money)		Koszt rezerwacji tej oferty. Na przykład 100 zł zniżki na ostateczny rachunek, gdy stolik jest zarezerwowany za 15 zł.
booking_cost_unit	enum (FeeUnit)		Jednostka kosztu rezerwacji. Na przykład na osobę lub na transakcję.
convenience_fee	obiekt (Fee)
booking_cost_adjustable	wartość logiczna		Czy koszt rezerwacji można odliczyć, tzn. czy koszt rezerwacji jest odejmowany od rachunku końcowego. Na przykład: 30% zniżki na kolację z rezerwacją. Koszt rezerwacji wynosi 15 USD i zostanie doliczony do ostatecznego rachunku. Ostateczna kwota do zapłaty: łączna kwota wydatków – 30% – 15 USD.
additional_fees	tablica obiektów (AdditionalFee)		Dodatkowe opłaty, które są pobierane od użytkownika. Przykłady: opłata za wygodę, obsługę, dostawę, opakowanie, usługę itp.
offer_discount_type	enum (OfferDiscountType)		Typ rabatu.
gift_card_info	object (GiftCardInfo)		Szczegóły dotyczące ofert kart podarunkowych.

Nazwa pola	Typ	Wymaganie	Opis
currency_code	tekst		Trzyliterowy kod waluty zdefiniowany w normie ISO 4217.
units	liczba		Jednostki całkowite kwoty. Jeśli na przykład currencyCode to "USD", to 1 jednostka to 1 dolar amerykański.
nanos	liczba		Liczba jednostek nano (10^-9) kwoty. Wartość musi się mieścić w przedziale od -999 999 999 do +999 999 999 (włącznie). Jeśli units jest liczbą dodatnią, nanos musi być liczbą dodatnią lub zerem. Jeśli units wynosi zero, nanos może być liczbą dodatnią, ujemną lub zerem. Jeśli units jest ujemna, nanos musi być ujemna lub wynosić zero. Na przykład kwota -1,75 USD jest reprezentowana jako units=-1 i nanos=-750 000 000.

Nazwa pola	Typ	Wymaganie	Opis
unit	enum (FeeUnit)
type	enum (FeeType)
	oneOf (cost)		Można ustawić tylko jedno z pól w tym elemencie oneOf.

Nazwa pola	Typ	Wymaganie	Opis
min_amount	object (Money)
max_amount	obiekt (Money)

Nazwa pola	Typ	Wymaganie	Opis
name	tekst	Wymagane	Nazwa dodatkowej opłaty. Przykłady: opłata za wygodę, opłata manipulacyjna itp. Wymagane.
fee	object (Fee)

Nazwa pola	Typ	Wymaganie	Opis
	oneOf (denomination_type)		Można ustawić tylko jedno z pól w tym polu oneOf.

Nazwa pola	Typ	Wymaganie	Opis
amounts	tablica obiektów (Money)		Lista wszystkich dostępnych nominałów (np. [100, 500, 1000]).

Nazwa pola	Typ	Wymaganie	Opis
combinable_with_other_offers	wartość logiczna		Czy tę ofertę można łączyć z innymi ofertami. Jeśli ta wartość jest prawdziwa, partnerzy mogą określić, z jakimi ofertami można łączyć tę ofertę. Jeśli ustawione są zarówno kategorie ofert, które można łączyć, jak i identyfikatory ofert, które można łączyć, każda oferta spełniająca jeden z powyższych warunków będzie mogła być łączona.
combinable_offer_categories	tablica typu enum (OfferCategory)		Lista typów ofert, z którymi można połączyć tę ofertę. Na przykład tę ofertę można łączyć z innymi kuponami. Jeśli atrybut combinable_with_other_offers ma wartość true, a to pole nie jest ustawione, wszystkie typy będą mogły być łączone.
combinable_offer_ids	tablica ciągów znaków		Lista identyfikatorów ofert, z którymi można połączyć tę ofertę. Niektóre oferty można łączyć tylko z określonymi innymi identyfikatorami ofert (można je uznać za oferty nadrzędne). Jeśli pole combinable_with_other_offers ma wartość true, a to pole nie jest ustawione, wszystkie identyfikatory ofert będą mogły być łączone.
inclusions	tablica obiektów (OfferCondition)		Lista warunków, które muszą być spełnione, aby oferta była ważna (np. napoje bezalkoholowe, jedzenie).
exclusions	tablica obiektów (OfferCondition)		Lista warunków, które unieważniają ofertę (np. bufet, oferty łączone i koktajle).
min_guest	liczba		Minimalna liczba osób wymagana do skorzystania z oferty. Uwaga: to pole dotyczy tylko rezerwacji stolików i nie powinno być używane w innych branżach.
food_offer_restrictions	object (FoodOfferRestrictions)		Ograniczenia dotyczące ofert żywności.
max_redemption_count	liczba		Ograniczenia dotyczące liczby przypadków, w których można skorzystać z oferty. Wartość 0 oznacza brak limitów. Na przykład wartość 3 oznacza, że użytkownik może skorzystać z tej oferty 3 razy.
max_total_discount_value	obiekt (Money)		Maksymalny rabat, z którego można skorzystać w ramach wielu transakcji w tej ofercie.
special_conditions	tablica ciągów znaków		Warunki specjalne oferty, które muszą być widoczne dla użytkownika. Przykłady: „Obowiązuje tylko w przypadku płatności w [obszar]”, „Nie dotyczy płatności online”, „Kupon podarunkowy MOŻNA wykorzystać podczas wyprzedaży”.

Nazwa pola	Typ	Wymaganie	Opis
description	tekst

Nazwa pola	Typ	Wymaganie	Opis
meal_types	tablica typu enum (MealType)		Rodzaje posiłków, których może dotyczyć oferta, np. lunch lub kolacja. Jeśli nie zostanie ustawiona, oferta może być zastosowana do wszystkich rodzajów posiłków.
restricted_to_certain_courses	wartość logiczna		Czy ofertę można zastosować tylko do określonych kursów.

Nazwa pola	Typ	Wymaganie	Opis
text	tekst		Tekst kuponu, który dostawca oferty chce wyświetlać użytkownikom.
code	tekst	Wymagane	Aby skorzystać z oferty, musisz podać kod kuponu. Wymagane.

Nazwa pola	Typ	Wymaganie	Opis
items	tablica obiektów (PaymentInstrumentItem)	Wymagane	Lista instrumentów płatniczych, których można użyć do skorzystania z oferty. Wymagane.
provider_name	tekst		Nazwa dostawcy instrumentu płatniczego. Może to być partner bankowy, nazwa banku itp. Na przykład: American Express, HDFC, ICICI.

Nazwa pola	Typ	Wymaganie	Opis
type	enum (PaymentInstrumentType)	Wymagane	Rodzaj instrumentu płatniczego. Wymagane.
name	tekst	Wymagane	Nazwa instrumentu płatniczego, np. nazwa karty kredytowej. Na przykład: HDFC Infinia, American Express Platinum. Wymagane.

Nazwa pola	Typ	Wymaganie	Opis
name	tekst	Wymagane	Nazwa subskrypcji. Wymagane.
subscription_auto_added	wartość logiczna		Czy subskrypcja jest dodawana automatycznie, gdy użytkownik skorzysta z tej oferty.
cost	object (Money)	Wymagane	Koszt subskrypcji. Wymagane.
subscription_duration	obiekt (Duration)	Wymagane	Okres ważności subskrypcji w ramach kosztu abonamentu. Wymagane.
terms_and_conditions_url	tekst		URL warunków partnera dotyczących tej subskrypcji.

Nazwa pola	Typ	Wymaganie	Opis
seconds	liczba		Sekundy ze znakiem w przedziale czasu. Musi mieścić się w zakresie od -315 576 000 000 do +315 576 000 000 włącznie. Uwaga: te granice są obliczane na podstawie tego wzoru: 60 s/min * 60 min/godz. * 24 godz./dzień * 365,25 dni/rok * 10 000 lat.
nanos	liczba		Ułamki sekundy ze znakiem o rozdzielczości nanosekundy w zakresie czasu. Czasy trwania krótsze niż sekunda są reprezentowane przez pole 0 seconds i pole nanos z wartością dodatnią lub ujemną. W przypadku czasów trwania wynoszących co najmniej 1 sekundę wartość pola nanos musi być różna od zera i mieć ten sam znak co pole seconds. Wartość musi mieścić się w zakresie od -999 999 999 do +999 999 999 włącznie.

Nazwa pola	Typ	Wymaganie	Opis
url	tekst		URL warunków korzystania z usługi partnera.
restricted_to_certain_users	wartość logiczna		Czy oferta jest ograniczona do niektórych użytkowników.
terms_and_conditions	tekst		Główny tekst warunków podany przez partnera.
additional_terms_and_conditions	tablica ciągów znaków		Warunki dodatkowe oprócz głównych warunków partnera.

Nazwa pola	Typ	Wymaganie	Opis
valid_period	object (ValidityRange)		Sygnatura czasowa rozpoczęcia i zakończenia okresu ważności oferty. Te godziny muszą reprezentować różne dni, tzn. czas rozpoczęcia musi być ustawiony na 00:00 (początek dnia), a czas zakończenia na 00:00 (wyłącznie) w dniu zakończenia okresu ważności.
time_of_day	tablica obiektów (TimeOfDayWindow)		Określa prawidłowy przedział czasu w danym dniu i dni, w których oferta jest dostępna. W przypadku przedziałów czasowych obejmujących północ (np. od 22:00 do 2:00) użyj oddzielnych okien dla każdego dnia: jednego kończącego się o 23:59:59 i drugiego rozpoczynającego się o 00:00 następnego dnia. Na przykład: poniedziałek: 10:00–17:00 wtorek: 10:00–14:00 wtorek: 17:00–19:00 środa, czwartek, piątek, sobota, niedziela: 15:00–19:00 Jeśli nie ustawiono żadnych godzin, oznacza to, że oferta jest dostępna przez cały czas w okresie valid_period.
time_exceptions	tablica obiektów (ValidTimeException)		Określa wyjątki od powyższych wartości valid_period i valid_time_of_week
date_exceptions	tablica obiektów (Date)		Określa wyjątki (w dniach) od powyższych wartości valid_period i time_of_day
validity_scope	enum (ValidityScope)		Określa zakres okresu ważności.
validity_duration_in_days	liczba		Okres ważności (w dniach) kuponu po zakupie.

Nazwa pola	Typ	Wymaganie	Opis
valid_from_time	object (Timestamp)	Wymagane	Czas rozpoczęcia zakresu (włącznie). Wymagane.
valid_through_time	object (Timestamp)		Czas zakończenia zakresu (wyłącznie). Jeśli nie jest ustawiona, oznacza to, że ten okres nigdy się nie kończy. Opcjonalnie:

Nazwa pola	Typ	Wymaganie	Opis
seconds	liczba		Reprezentuje sekundy czasu UTC od epoki uniksowej 1970-01-01T00:00:00Z. Musi mieścić się w zakresie od -62135596800 do 253402300799 włącznie (co odpowiada zakresowi od 0001-01-01T00:00:00Z do 9999-12-31T23:59:59Z).
nanos	liczba		Nieujemne ułamki sekundy w rozdzielczości nanosekundowej. To pole zawiera nanosekundową część czasu trwania, a nie alternatywę dla sekund. Ujemne wartości sekund z ułamkami muszą nadal mieć nieujemne wartości nanosekund, które liczą czas do przodu. Musi mieścić się w zakresie od 0 do 999 999 999 włącznie.

Nazwa pola	Typ	Wymaganie	Opis
time_windows	object (TimeOfDayRange)	Wymagane	Przedział czasu, w którym można złożyć lub zrealizować zamówienie. Wymagane.
day_of_week	tablica typu enum (DayOfWeek)		Lista dni tygodnia, w których stosowane są okna. Jeśli nie ustawisz żadnej wartości, będzie to oznaczać, że zasada obowiązuje we wszystkie dni tygodnia. Opcjonalnie:
day_of_month	tablica obiektów (DayOfMonthRange)		Dni miesiąca, w których stosowane są okna. Jeśli nie ustawisz żadnego dnia, oznacza to, że zasada obowiązuje we wszystkie dni miesiąca. Opcjonalnie:

Nazwa pola	Typ	Wymaganie	Opis
open_time	object (TimeOfDay)		Czas wskazujący godzinę rozpoczęcia dnia w zakresie (włącznie). Jeśli nie jest ustawiona, oznacza to 00:00:00. Opcjonalnie:
close_time	object (TimeOfDay)		Czas wskazujący godzinę zakończenia dnia w zakresie (wykluczając najwyższą wartość). Jeśli nie jest ustawiona, oznacza to godzinę 23:59:59. Opcjonalnie:

Nazwa pola	Typ	Wymaganie	Opis
hours	liczba		Godziny w formacie 24-godzinnym. Wartość musi być równa lub większa niż 0 i zwykle nie może być większa niż 23. Interfejs API może zezwalać na wartość „24:00:00” w przypadku takich scenariuszy jak godzina zamknięcia firmy.
minutes	liczba		Minuty w godzinie. Wartość musi być równa lub większa niż 0 i równa lub mniejsza niż 59.
seconds	liczba		Sekundy w minucie. Wartość musi być równa lub większa niż 0 i zwykle nie może być większa niż 59. Interfejs API może zezwalać na wartość 60, jeśli dopuszcza sekundy przestępne.
nanos	liczba		Ułamki sekund w nanosekundach. Wartość musi być równa lub większa niż 0 i mniejsza lub równa 999 999 999.

Nazwa pola	Typ	Wymaganie	Opis
valid_from_day	liczba	Wymagane	Dzień rozpoczęcia zakresu (włącznie). Wymagane.
valid_through_day	liczba		Ostatni dzień zakresu (włącznie). Jeśli nie jest ustawiony, oznacza to, że ten zakres obejmuje jeden dzień (valid_from_day). Opcjonalnie:

Nazwa pola	Typ	Wymaganie	Opis
exceptional_period	obiekt (ValidityRange)		Sygnatura czasowa rozpoczęcia i zakończenia okresu, w którym oferta jest nieważna. Te godziny muszą reprezentować różne dni, tzn. godzina rozpoczęcia musi być ustawiona na 00:00 (początek dnia), a godzina zakończenia na 00:00 (wyłącznie) w dniu, w którym kończy się okres wyjątku.

Nazwa pola	Typ	Wymaganie	Opis
year	liczba		Rok daty. Musi mieścić się w zakresie od 1 do 9999 lub wynosić 0, jeśli określasz datę bez roku.
month	liczba		Miesiąc roku. Musi mieścić się w zakresie od 1 do 12 lub wynosić 0, jeśli określasz rok bez miesiąca i dnia.
day	liczba		Dzień miesiąca. Wartość musi mieścić się w zakresie od 1 do 31 i być prawidłowa w przypadku danego roku i miesiąca lub wynosić 0, jeśli określasz sam rok lub rok i miesiąc, gdy dzień nie jest istotny.

Nazwa	Opis
OFFER_SOURCE_UNSPECIFIED
OFFER_SOURCE_AGGREGATOR

Nazwa	Opis
ACTION_TYPE_UNSPECIFIED
ACTION_TYPE_FOOD_DELIVERY	Oferta dotyczy usług dostawy jedzenia.
ACTION_TYPE_FOOD_TAKEOUT	Oferta dotyczy zamówień jedzenia na wynos lub z odbiorem.
ACTION_TYPE_DINING	Oferta dotyczy posiłków na miejscu w restauracji.
ACTION_TYPE_APPOINTMENT	Oferta dotyczy usług rezerwacji spotkań.
ACTION_TYPE_SHOPPING_IN_STORE	Oferta dotyczy zakupów offline w sklepie stacjonarnym.

Nazwa	Opis
OFFER_MODE_OTHER	Używaj w przypadku metod realizacji, które nie są objęte innymi konkretnymi trybami.
OFFER_MODE_WALK_IN	Oferta jest dostępna w przypadku wizyt w obiekcie bez wcześniejszej rezerwacji.
OFFER_MODE_FREE_RESERVATION	Oferta obowiązuje, gdy użytkownik dokonuje rezerwacji, która nie wymaga opłaty z góry.
OFFER_MODE_PAID_RESERVATION	Oferta obowiązuje, gdy użytkownik dokonuje rezerwacji, która wymaga płatności z góry.
OFFER_MODE_ONLINE_ORDER	Oferta dotyczy zamówień składanych na stronie internetowej lub platformie cyfrowej.
OFFER_MODE_GIFT_CARD_PURCHASE	Oznacza, że zakup karty podarunkowej jest głównym krokiem wymaganym do skorzystania z oferty.

Nazwa	Opis
OFFER_CATEGORY_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani domyślnej.
OFFER_CATEGORY_BASE_OFFER
OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER
OFFER_CATEGORY_ADD_ON_COUPON_OFFER
OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER
OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER

Nazwa	Opis
FEE_UNIT_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani wartości domyślnej.
FEE_UNIT_PER_GUEST
FEE_UNIT_PER_TRANSACTION

Nazwa	Opis
FEE_TYPE_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani wartości domyślnej.
FEE_TYPE_FIXED
FEE_TYPE_VARIABLE

Nazwa	Opis
OFFER_DISCOUNT_TYPE_UNSPECIFIED
OFFER_DISCOUNT_TYPE_INSTANT_DISCOUNT
OFFER_DISCOUNT_TYPE_CASHBACK
OFFER_DISCOUNT_TYPE_REWARD_POINT

Nazwa	Opis
MEAL_TYPE_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani wartości domyślnej.
MEAL_TYPE_BREAKFAST
MEAL_TYPE_LUNCH
MEAL_TYPE_DINNER

Nazwa	Opis
PAYMENT_INSTRUMENT_TYPE_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani wartości domyślnej.
PAYMENT_INSTRUMENT_CREDIT_CARD
PAYMENT_INSTRUMENT_DEBIT_CARD
PAYMENT_INSTRUMENT_BANK_ACCOUNT
PAYMENT_INSTRUMENT_UPI
PAYMENT_INSTRUMENT_ONLINE_WALLET
PAYMENT_INSTRUMENT_NETBANKING

Nazwa	Opis
DAY_OF_WEEK_UNSPECIFIED	Dzień tygodnia nie został określony.
MONDAY	Poniedziałek
TUESDAY	Tuesday (wtorek)
WEDNESDAY	Wednesday (środa)
THURSDAY	Thursday (czwartek)
FRIDAY	Friday (piątek)
SATURDAY	Saturday (sobota)
SUNDAY	Niedziela

Nazwa	Opis
VALIDITY_SCOPE_UNSPECIFIED
VALIDITY_SCOPE_CLAIM
VALIDITY_SCOPE_REDEEM

Nazwa	Opis
OFFER_TAG_UNSPECIFIED	W plikach danych nie należy używać wartości wyliczeniowej UNSPECIFIED ani wartości domyślnej.
OFFER_TAG_NEW_YEAR_SPECIAL
OFFER_TAG_VALENTINES_SPECIAL

Nazwa	Opis
AVAILABILITY_LEVEL_UNSPECIFIED
AVAILABILITY_LEVEL_LOW	Wskazuje, że oferta jest bliska wyczerpania. Zachęcamy użytkowników do wykorzystania nagrody, zanim stanie się niedostępna. W przyszłości możemy dodać poziomy MEDIUM i HIGH.

Nazwa pola	Typ	Wymaganie	Opis
discount_percent	liczba	Wykluczają się wzajemnie z: discount_value, other_offer_detail_text	Odsetek rachunku, który jest objęty rabatem. [0, 100] W przypadku ofert 1+1 lub 50% zniżki, które dotyczą całego posiłku (np. bufet 1+1, 1+1 na cały rachunek, 1+1 na menu), tę wartość można ustawić na 50.
discount_value	obiekt (Money)	Wykluczają się wzajemnie z: discount_percent, other_offer_detail_text	Stała wartość rabatu.
other_offer_detail_text	tekst	Wzajemnie wykluczające się z discount_percent, discount_value	Dowolny tekst opisujący rabat. W przypadku konkretnych ofert 1+1 (np. 1+1 napój, +1 danie główne, 1+1 wybrane pozycje menu) należy opisać te szczegóły tutaj.

Nazwa pola	Typ	Wymaganie	Opis
amount	object (Money)	Wyklucza się wzajemnie z: amount_range
amount_range	object (MoneyRange)	Wyklucza się wzajemnie z: amount

Nazwa pola	Typ	Wymaganie	Opis
fixed_denominations	object (FixedDenominations)	Wyklucza się wzajemnie z: custom_range	Używane, gdy karta podarunkowa jest dostępna w określonych, stałych kwotach.
custom_range	obiekt (MoneyRange)	Wzajemnie wykluczające się z fixed_denominations	Używane, gdy marka umożliwia użytkownikom wybór niestandardowej (elastycznej) wartości nominalnej w określonym zakresie.

Przesyłanie pliku danych

Plik danych z ofertami musi zostać przesłany na serwer SFTP pliku danych Generic. Postępuj zgodnie z instrukcjami podanymi w samouczku dotyczącym korzystania z serwera SFTP pliku danych ogólnego i w pliku deskryptora ustaw wartość name na google.offer.

Częstotliwość przesyłania

Zazwyczaj Google oczekuje 1 przesłania pliku danych dziennie. Częstotliwość można zwiększyć lub zmniejszyć w zależności od częstotliwości aktualizacji ofert po Twojej stronie, aby zapewnić stale wysoką precyzję. Skontaktuj się z osobą kontaktową w Google.

Dane pojawią się w Google po kilku godzinach.

Kategoryzacja ofert

• OFFER_CATEGORY_BASE_OFFER: oferty, z których można skorzystać niezależnie, bez łączenia z innymi ofertami. Obejmuje ona m.in:
  • rabaty stałe na cały rachunek (np. 20% zniżki);
  • Oferty subskrypcji (np. bezpłatny deser w ramach subskrypcji)
  • oferty płatności w przypadkach, gdy nie ma innych ofert podstawowych dla restauracji;
  • Uwaga: oferty zwolnienia z opłat lub obniżenia opłat na poziomie platformy nie powinny być ustawiane jako oferty podstawowe.
• Oferty dodatkowe: oferty, które wymagają skorzystania z oferty podstawowej. Są to:
  • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER (np. dodatkowe 10% zniżki przy płatności określoną kartą kredytową)
  • OFFER_CATEGORY_ADD_ON_COUPON_OFFER (np. bezpłatny napój z określonym kodem kuponu);
  • OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER (np. dodatkowe 10% rabatu dla subskrybentów)
  • OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER (np. bezpłatna dostawa lub obniżona opłata)

Inne rzeczy, które warto wziąć pod uwagę:

• Oferty obniżenia lub zniesienia opłat na całej platformie nie powinny być ustawiane jako oferty podstawowe (OFFER_CATEGORY_BASE_OFFER). Powinny być ustawiane tylko jako OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER, aby uzupełniać inną aktywną ofertę podstawową.
• Jeśli restauracja nie ma ustawionej oferty podstawowej, oferty dodatkowe nie będą się wyświetlać. Jeśli nie ma oferty podstawowej, każda oferta płatności, subskrypcji lub kuponu, z której można skorzystać bez konieczności dodawania jej do innej oferty, musi być oznaczona jako OFFER_CATEGORY_BASE_OFFER.
  • W zależności od typu należy ustawić odpowiednie dane dla PaymentInstrument, Subscription lub Coupon.
  • Partnerzy muszą dostarczyć 2 kopie każdej z tych ofert, aby uwzględnić scenariusze, w których działają one zarówno jako oferty podstawowe, jak i oferty dodatkowe. Tekst oferty dodatkowej można następnie ustawić dla wielu restauracji za pomocą entity_ids lub add_on_offer_applicable_to_all_entities.
• Jeśli restauracja ma kilka ofert podstawowych, które można łączyć, wszystkie oferty podstawowe powinny być oznaczone jako OFFER_CATEGORY_BASE_OFFER, a oferty podstawowe, które są ofertami płatności, subskrypcji lub kuponów, powinny być wysyłane dodatkowo jako odpowiedni typ oferty dodatkowej.
• ValidityPeriod powinno być używane do aktywowania ofert dodatkowych jako ofert podstawowych tylko wtedy, gdy nie ma aktywnej oferty podstawowej.
• Konsolidacja identycznych ofert według instrumentu płatniczego: jeśli kilka instrumentów płatniczych ma dokładnie tę samą wartość rabatu (np. karta kredytowa, karta debetowa i net banking oferują 5% zniżki), zgrupuj je w ramach jednego skonsolidowanego obiektu Offer, zamiast wysyłać osobne, zduplikowane oferty. Aby to zrobić, wypełnij listę payment_instrument.items wszystkimi odpowiednimi instrumentami płatniczymi. Zmniejsza to bałagan w układzie interfejsu Google i zapobiega potencjalnym spadkom pozycji w rankingu z powodu nadmiernych ograniczeń dotyczących duplikatów.

Przykładowe scenariusze:

• Restauracja oferuje 5% zniżki przy płatności określoną kartą kredytową i bezpłatny napój przy użyciu określonego kodu kuponu.

  • Oferta karty kredytowej z 5% zniżką powinna zostać wysłana w 2 egzemplarzach, z których jeden powinien być oznaczony jako OFFER_CATEGORY_BASE_OFFER, a drugi jako OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER, ze szczegółami PaymentInstrument.
  • Ofertę napoju bez opłat z kodem kuponu należy przesłać jako OFFER_CATEGORY_ADD_ON_COUPON_OFFER ze szczegółami Coupon.

• Restauracja oferuje 10% zniżki dla klientów bez rezerwacji i 5% zniżki przy płatności określoną kartą kredytową. Obie zniżki można łączyć.

  • Oferta 10% zniżki dla klientów bez rezerwacji powinna być oznaczona tagiem OFFER_CATEGORY_BASE_OFFER.
  • Oferta rabatu 5% za płatność kartą kredytową powinna mieć 2 kopie, z których jedna jest oznaczona tagiem OFFER_CATEGORY_BASE_OFFER, a druga tagiem OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.

• Restauracja oferuje 10% zniżki tylko na lunch w dni powszednie i 5% zniżki w dowolnym momencie, gdy płatność jest dokonywana określoną kartą kredytową.

  • Oferta 10% rabatu powinna mieć ustawioną wartość ValidityPeriod, aby wskazywać tylko godziny lunchu w dni powszednie.
  • Oferta rabatu 5% za płatność kartą kredytową powinna zostać wysłana w 2 egzemplarzach.
    • Jedna kopia powinna być oznaczona jako OFFER_CATEGORY_BASE_OFFER z uwzględnieniem szczegółów PaymentInstrument. ValidityPeriod należy ustawić tak, aby wykluczyć godziny lunchu w dni robocze, gdy aktywna jest oferta 10% zniżki na lunch.
    • Jedna kopia powinna być oznaczona jako OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER i zawierać szczegóły PaymentInstrument.
  • Wszystkie pozostałe oferty płatności w przypadku tej restauracji powinny być oznaczone tagiem OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.

Proces tworzenia i wdrażania

Podczas integracji Portal dla partnerów będzie Ci pomagać, dostarczając informacje i opinie na podstawie Twoich postępów. Proces tworzenia będzie przebiegać w następujący sposób:

• Integracja zostanie najpierw opracowana w środowisku Sandbox. W środowisku Google Sandbox należy używać eksportu danych produkcyjnych (lub nawet bezpośrednio danych produkcyjnych). Dzięki temu podczas programowania uwzględnisz wszystkie przypadki skrajne, a Google będzie mogła ocenić jakość danych i lepiej Ci pomóc na podstawie Twojego modelu danych.
• Gdy zaczniesz regularnie przesyłać kompletne i codzienne pliki danych o sprzedawcach, usługach i ofertach w środowisku piaskownicy Google, zespół Google oceni Twoje pliki danych. Gdy zespół Google zatwierdzi kod, możesz go przesłać do środowiska produkcyjnego i zacząć wysyłać dane produkcyjne do środowiska produkcyjnego Google.
• Po pełnym przetestowaniu integracji produkcyjnej zespół Google również przeprowadzi testy. Po zakończeniu wszystkich testów integracja zostanie uruchomiona.

Monitorowanie

Aby zapewnić użytkownikom dobre wrażenia, Google sprawdzi, czy podane oferty są prawidłowe i zgodne z naszymi zasadami przed ich uruchomieniem i po nim. W tym celu Google będzie korzystać z połączenia weryfikacji manualnej i automatycznej. Wyniki tych weryfikacji będą dostępne w panelu ofert w Centrum działań (tylko w środowisku produkcyjnym). Wyniki tego monitorowania mogą mieć wpływ na ranking ofert.

Upewnij się, że strona wczytuje się w całości z ofertami w czasie krótszym niż 5 sekund. W przeciwnym razie zostanie to uznane za błąd i oznaczone jako Bad link.

Automatyczne sprawdzanie (roboty)

Zespół ds. jakości Google wdraża roboty indeksujące. Roboty to skrypty, które automatyzują przeglądarkę internetową, aby wykonywać kliknięcia i wyodrębniać informacje o ofertach wyłącznie na potrzeby testów jakości.

Liczba zapytań

Jeśli na przykład zdecydujemy się wysyłać 5000 kontroli dziennie, oznacza to, że 5000 razy dziennie (równomiernie rozłożone w ciągu dnia, czyli mniej więcej raz na 17 sekund) nasz robot wykona wszystkie te czynności, które wykonałby zwykły użytkownik:

• Zacznij od wyszukiwarki Google i kliknij link partnera.
• Znajdź informacje o ofercie.
• Jeśli oferta wymaga rezerwacji, użytkownik przejdzie do procesu rezerwacji, aby potwierdzić, że oferta jest dostępna w określonym czasie (rezerwacja nie zostanie dokonana).

Wykrywanie skrobaków sieciowych

Aby zapobiec zablokowaniu skrobaka (co może doprowadzić do wniosku, że oferty są niedostępne), upewnij się, że Twój system zawsze zezwala naszemu skrobakowi na wysyłanie zapytań do Twojej strony. Aby zidentyfikować nasz skrobak:

• Klient użytkownika skrobaka sieciowego będzie zawierać ciąg „Google-Offers”:
  • Przykład: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko; Google-Offers) Chrome/104.0.5112.101 Safari/537.36
• Możesz też sprawdzić, czy wywołania pochodzą od Google, korzystając z odwrotnego wyszukiwania DNS, zgodnie z zaleceniami w artykule Weryfikowanie Googlebota i innych robotów Google. W naszym konkretnym przypadku odwrotne rozpoznawanie nazw DNS przebiega według tego wzorca: google-proxy-***-***-***-***.google.com.

Działanie techniczne

Buforowanie

Aby zmniejszyć obciążenie witryny partnera, nasze roboty są zwykle skonfigurowane tak, aby uwzględniać wszystkie standardowe nagłówki pamięci podręcznej HTTP występujące w odpowiedzi. Oznacza to, że w przypadku prawidłowo skonfigurowanych witryn unikamy wielokrotnego pobierania treści, które rzadko się zmieniają (np. bibliotek JavaScript). Więcej informacji o implementowaniu buforowania znajdziesz w dokumentacji dotyczącej buforowania HTTP.