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 (procentowa zniżka, zniżka w dolarach …), okresów ważności (określone godziny, dni tygodnia …), zastosowań (oferta może być używana tylko w przypadku niektórych usług) oraz 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 brunchowe w każdą niedzielę od 10:00 do 14:00
• 10% rabatu w przypadku oferty dla klientów bez rezerwacji, który można połączyć z 5% rabatem dla subskrybentów Premium i 5% rabatem, jeśli użytkownik zapłaci za pomocą Twojej aplikacji.

Uwaga: każda oferta musi mieć unikalny identyfikator. Gdy oferta otrzyma identyfikator, nie można jej zmienić. Jeśli oferta ulegnie zmianie, musi otrzymać nowy, niepowtarzalny identyfikator, a starą ofertę można usunąć.

Aby oferta została uwzględniona w integracji, musi pasować do technicznego modelu danych i spełniać nasze wymagania. Zapoznaj się z naszymi zasadami dotyczącymi ofert, aby mieć pewność, że Twoja integracja jest zgodna z zasadami, i uzyskać instrukcje dotyczące postępowania z ofertami, które nie spełniają wymagań technicznych.

Implementacja ofert

Integracja ofert składa się z 2 plików danych, które będą przesyłane codziennie lub z częstotliwością zapewniającą wysoką dokładność (czyli zmniejszającą nieaktualność):

• Jedno z tych rozwiązań:
  • Plik danych o sprzedawcach (przy użyciu konfiguracji Merchant)
  • Lub Plik danych o elementach (przy użyciu konfiguracji Generic)
• Oraz Plik danych o ofertach (przy użyciu konfiguracji Generic)

OfferFeed

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

Oferta

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 biorą udział w tej ofercie.
add_on_offer_applicable_to_all_entities	wartość logiczna		Jeśli wartość to „true”, oferta dotyczy wszystkich podmiotów w ramach agregatora. Dotyczy to 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 działania. Jeśli oferta może być udostępniana w ramach wielu typów usług, dla każdego typu usługi należy utworzyć zduplikowane oferty z unikalnymi identyfikatorami. 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) określająca poziom priorytetu oferty przypisany przez źródło. Gdy u 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	obiekt (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 forma płatności, czy ofertę można łączyć z innymi ofertami (i jakiego typu) itp. Wymagany.
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. Wymagany w przypadku offer_category: OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.
subscription	obiekt (Subscription)		Szczegóły subskrypcji. Wymagany 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. Opisuje okres, w którym oferta jest ważna, w tym godziny rozpoczęcia i zakończenia, dni tygodnia itp. Wymagane.
offer_url	tekst		Adres URL strony z ofertą sprzedawcy. Wymagany 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		Wymagane w przypadku ofert dotyczących kart podarunkowych, aby zidentyfikować markę oferującą daną ofertę.
availability_level	enum (AvailabilityLevel)		Poziom dostępności oferty.

OfferDetails

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 polu oneOf.
max_discount_value	obiekt (Money)		Maksymalny rabat, z którego można skorzystać. Na przykład rabat 10% do 100 PLN.
min_spend_value	obiekt (Money)		Minimalna wartość wydatków, aby skorzystać ze zniżki. Na przykład 10% zniżki, gdy łączna cena wynosi co najmniej 100 zł.
booking_cost	obiekt (Money)		Koszt rezerwacji tej oferty. Na przykład 100 zł zniżki na rachunek końcowy, gdy stolik zostanie zarezerwowany za 15 zł.
booking_cost_unit	enum (FeeUnit)		Jednostka kosztu rezerwacji. np. za osobę lub za transakcję.
convenience_fee	obiekt (Fee)
booking_cost_adjustable	wartość logiczna		Czy koszt rezerwacji można odliczyć, tzn. czy jest on odejmowany od rachunku końcowego. Na przykład: 30% zniżki na kolację po dokonaniu rezerwacji. Koszt rezerwacji wynosi 15 USD i zostanie odliczony od ostatecznego rachunku. Ostateczny rachunek: wydana kwota – 30% – 15 USD
additional_fees	tablica obiektów (AdditionalFee)		Dodatkowe opłaty pobierane od użytkownika. Przykłady: opłata za wygodę, obsługę, dostawę, opakowanie, opłata za usługę itp.
offer_discount_type	enum (OfferDiscountType)		Typ rabatu.
gift_card_info	obiekt (GiftCardInfo)		Szczegóły dotyczące ofert kart podarunkowych.

Pieniądze

Reprezentuje kwotę pieniędzy z określeniem rodzaju waluty.

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 [phone] (włącznie). Jeśli units jest liczbą dodatnią, nanos musi być liczbą dodatnią lub zerem. Jeśli units wynosi zero, nanos może być dodatnie, równe zero lub ujemne. Jeśli units jest ujemna, nanos musi być ujemna lub wynosić zero. Na przykład wartość –1,75 PLN jest reprezentowana jako units=-1 i nanos=-750000000.

Opłata

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

MoneyRange

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

AdditionalFee

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

GiftCardInfo

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

FixedDenominations

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

OfferRestrictions

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 combinable_offer_categories, jak i combinable_offer_ids, każda oferta spełniająca jeden z powyższych warunków będzie mogła być łączona z innymi.
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ą możliwe do łączenia.
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 identyfikatorami innych ofert (można je uznać za oferty nadrzędne). Jeśli wartość pola combinable_with_other_offers to „true”, a to pole nie jest ustawione, wszystkie identyfikatory ofert będzie można łączyć.
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 w restauracjach i nie powinno być używane w przypadku innych branż.
food_offer_restrictions	obiekt (FoodOfferRestrictions)		Ograniczenia dotyczące ofert gastronomicznych.
max_redemption_count	liczba		Ograniczenia dotyczące liczby możliwości wykorzystania tej 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		Specjalne warunki tej oferty, które muszą być wyświetlane użytkownikowi. Przykłady: „Tylko do płatności w [obszar]”, „Nie obejmuje płatności online”, „Voucher podarunkowy MOŻE być użyty podczas wyprzedaży”.

OfferCondition

Nazwa pola	Typ	Wymaganie	Opis
description	tekst

FoodOfferRestrictions

Nazwa pola	Typ	Wymaganie	Opis
meal_types	tablica typu enum (MealType)		Rodzaje posiłków, do których można zastosować ofertę, 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 oferta może być zastosowana tylko w przypadku niektórych kursów.

Kupon

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 użyć kodu kuponu. Wymagane.

PaymentInstrument

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.

PaymentInstrumentItem

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

Subskrypcja

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	obiekt (Money)	Wymagane	Koszt subskrypcji. Wymagane.
subscription_duration	obiekt (Duration)	Wymagane	Okres ważności subskrypcji w przypadku atrybutu koszt abonamentu. Wymagane.
terms_and_conditions_url	tekst		Adres URL warunków partnera dotyczących tej subskrypcji.

Czas trwania

Nazwa pola	Typ	Wymaganie	Opis
seconds	liczba		Podpisane sekundy przedziału czasu. Musi mieścić się w przedziale od -315 576 000 000 do [phone] 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. Musi mieścić się w zakresie od -999 999 999 do [phone] włącznie.

Warunki

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 do głównych warunków partnera.

ValidityPeriod

Nazwa pola	Typ	Wymaganie	Opis
valid_period	obiekt (ValidityRange)		Sygnatura czasowa rozpoczęcia i zakończenia okresu, w którym oferta jest ważna. Te godziny muszą przypadać w różnych dniach, tzn. godzina rozpoczęcia musi być 00:00 (początek dnia), a godzina zakończenia musi być 00:00 (wyłącznie) w dniu, w którym kończy się okres ważności.
time_of_day	tablica obiektów (TimeOfDayWindow)		Określa prawidłowy przedział czasu w danym dniu oraz dni, w których oferta jest dostępna. W przypadku przedziałów czasowych przekraczających północ (np. od 22:00 do 2:00) użyj osobnych 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. 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 żadnej wartości, oznacza to, że oferta jest dostępna przez cały czas w ramach valid_period.
time_exceptions	tablica obiektów (ValidTimeException)		Określa wyjątki od powyższych atrybutów valid_period i valid_time_of_week.
date_exceptions	tablica obiektów (Date)		Określa wyjątki w dniach od powyższego atrybutu valid_period i time_of_day.
validity_scope	enum (ValidityScope)		Określa zakres okresu ważności.
validity_duration_in_days	liczba		Czas (w dniach), przez jaki kupon jest ważny po zakupie.

ValidityRange

Zakres sygnatur czasowych zamknięty-otwarty.

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

Sygnatura czasowa

Nazwa pola	Typ	Wymaganie	Opis
seconds	liczba		Reprezentuje sekundy czasu UTC od epoki uniksowej 1970-01-01T00:00:00Z. Musi mieścić się w przedziale 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 część czasu trwania w nanosekundach, 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.

TimeOfDayWindow

Obiekt TimeWindow to złożona jednostka, która opisuje listę okien, w których można złożyć lub zrealizować zamówienie użytkownika.

Nazwa pola	Typ	Wymaganie	Opis
time_windows	obiekt (TimeOfDayRange)	Wymagane	Okres, 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ą przedziały czasu. Jeśli nie ustawiono żadnego dnia, oznacza to, że zasada obowiązuje we wszystkie dni tygodnia. Opcjonalnie:
day_of_month	tablica obiektów (DayOfMonthRange)		Dni w miesiącu, w których stosowane są przedziały czasu. Jeśli nie jest ustawiona, oznacza to, że obowiązuje przez wszystkie dni miesiąca. Opcjonalnie:

TimeOfDayRange

Zakres czasu zamknięty-otwarty.

Nazwa pola	Typ	Wymaganie	Opis
open_time	obiekt (TimeOfDay)		Godzina wskazująca początek dnia w zakresie (włącznie). Jeśli nie jest ustawiona, oznacza to 00:00:00. Opcjonalnie:
close_time	obiekt (TimeOfDay)		Obiekt Time wskazujący godzinę zakończenia dnia w zakresie (wykluczającą). Jeśli nie jest ustawiona, oznacza to 23:59:59. Opcjonalnie:

TimeOfDay

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.

DayOfMonthRange

Zakres dni miesiąca, który obowiązuje we wszystkich miesiącach roku.

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:

ValidTimeException

Nazwa pola	Typ	Wymaganie	Opis
exceptional_period	obiekt (ValidityRange)		Sygnatury czasowe rozpoczęcia i zakończenia, w których oferta nie jest ważna. Te godziny muszą przypadać w różnych dniach, tzn. godzina rozpoczęcia musi być 00:00 (początek dnia), a godzina zakończenia musi być 00:00 (bez włączenia) w dniu, w którym kończy się okres wyłączenia.

Data

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 albo rok i miesiąc, w których dzień nie ma znaczenia.

OfferSource

Nazwa	Opis
OFFER_SOURCE_UNSPECIFIED
OFFER_SOURCE_AGGREGATOR

ActionType

Reprezentuje tryb realizacji oferty. Jeśli ofertę można udostępniać w kilku trybach realizacji, należy utworzyć zduplikowane oferty dla każdego trybu realizacji.

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 w restauracji na terenie obiektu.
ACTION_TYPE_SHOPPING_IN_STORE	Oferta dotyczy zakupów w sklepie stacjonarnym.

OfferMode

Określa metodę lub kanał, za pomocą którego użytkownik może skorzystać z oferty.

Nazwa	Opis
OFFER_MODE_OTHER	Używaj w przypadku metod realizacji zamówień, których nie obejmują inne konkretne tryby.
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 jest ważna w przypadku zamówień złożonych za pomocą strony internetowej lub platformy cyfrowej.
OFFER_MODE_GIFT_CARD_PURCHASE	Oznacza, że zakup karty podarunkowej jest głównym krokiem wymaganym do skorzystania z oferty.

OfferCategory

Kategoria oferty. Oferta podstawowa to standardowa oferta dostępna dla wszystkich klientów, np. 10% rabatu na wydatki powyżej 100 PLN. Oferta podstawowa ograniczona kuponem lub instrumentem płatniczym będzie miała ustawione odpowiednie pola. Mamy też oferty dodatkowe, takie jak ADD_ON_PAYMENT_OFFER. Takie oferty można łączyć z innymi, aby uzyskać dodatkowe rabaty.

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

FeeUnit

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

FeeType

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

OfferDiscountType

Nazwa	Opis
OFFER_DISCOUNT_TYPE_UNSPECIFIED
OFFER_DISCOUNT_TYPE_INSTANT_DISCOUNT
OFFER_DISCOUNT_TYPE_CASHBACK
OFFER_DISCOUNT_TYPE_REWARD_POINT

MealType

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

PaymentInstrumentType

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

DzieńTygodnia

Reprezentuje dzień tygodnia.

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

ValidityScope

Zakres okresu ważności, czyli dokładnie do jakich działań odnosi się ten okres.

Nazwa	Opis
VALIDITY_SCOPE_UNSPECIFIED
VALIDITY_SCOPE_CLAIM
VALIDITY_SCOPE_REDEEM

OfferTag

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

AvailabilityLevel

Wskazuje stan zapasów lub dostępność oferty.

Nazwa	Opis
AVAILABILITY_LEVEL_UNSPECIFIED
AVAILABILITY_LEVEL_LOW	Wskazuje, że oferta jest prawie niedostępna. Zachęcamy użytkowników do wykorzystania go, zanim stanie się niedostępny. W przyszłości możemy dodać poziomy ŚREDNI i WYSOKI.

offer_specification

Rabat może być procentem lub stałą wartością odjętą od łącznej wartości. Na przykład: 10% rabatu na rachunek końcowy. 2. 15 USD zniżki na zamówienie. Sprzedawcy mogą też oferować rabaty niestandardowe, np. „kup jeden produkt i otrzymaj jeden w cenie”, w odpowiednich polach specyfikacji. Wymagane.

Nazwa pola	Typ	Wymaganie	Opis
discount_percent	liczba	Wzajemnie wykluczające się z discount_value, other_offer_detail_text	Procent rachunku, od którego naliczana jest zniżka. [0, 100] W przypadku ofert typu 1+1 lub 50% zniżki na cały posiłek (np. 1+1 na bufet, 1+1 na cały rachunek, 1+1 na zestaw) wartość ta może wynosić 50.
discount_value	obiekt (Money)	Wzajemnie wykluczające się 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 napoje, +1 danie główne, 1+1 wybrane pozycje menu) należy podać tutaj szczegóły.

koszt

Nazwa pola	Typ	Wymaganie	Opis
amount	obiekt (Money)	Wzajemnie wykluczające się z amount_range
amount_range	obiekt (MoneyRange)	Wzajemnie wykluczające się z amount

denomination_type

Nazwa pola	Typ	Wymaganie	Opis
fixed_denominations	obiekt (FixedDenominations)	Wzajemnie wykluczające się 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ę. Skonsultuj się z osobą kontaktową w Google.

Zanim dane pojawią się w Google, może upłynąć kilka godzin.

Uwaga: jeśli między 2 uruchomieniami naszej ścieżki weryfikacji (co ok. 2 godziny) prześlesz więcej niż 1 plik danych, zweryfikowany zostanie tylko najnowszy plik danych, a pozostałe pliki danych pozostaną w stanie Processing.

Kategoryzacja ofert

• OFFER_CATEGORY_BASE_OFFER: oferty, które można wykorzystać 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 przypadku braku 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ą wykorzystania oferty podstawowej. Są to:
  • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER (np. dodatkowe 10% zniżki za płatność 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żające lub znoszące opłaty na całej platformie nie powinny być ustawiane jako oferty podstawowe (OFFER_CATEGORY_BASE_OFFER). Należy je ustawiać 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ą przesłać 2 kopie każdej z tych ofert, aby uwzględnić scenariusze, w których pełnią one funkcję zarówno ofert podstawowych, jak i dodatkowych. 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 wiele 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 dotyczącymi płatności, subskrypcji lub kuponów, powinny być dodatkowo przesyłane jako odpowiedni typ oferty dodatkowej.
• ValidityPeriod należy używać 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 taką samą wartość rabatu (np. karta kredytowa, karta debetowa i bankowość internetowa oferują 5% rabatu), zgrupuj je w ramach jednego skonsolidowanego obiektu Offer zamiast wysyłać oddzielne 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 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 5% rabatu na kartę kredytową powinna zostać wysłana w 2 kopiach, z których jedna powinna być oznaczona jako OFFER_CATEGORY_BASE_OFFER, a druga jako OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER z uwzględnieniem szczegółów PaymentInstrument.
  • Oferta bezpłatnego napoju z kodem kuponu powinna być wysłana jako OFFER_CATEGORY_ADD_ON_COUPON_OFFER z uwzględnieniem Coupon szczegółów.

• 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% rabatu dla klientów, którzy przyjdą do sklepu, 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 kopiach.
    • 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 z uwzględnieniem szczegółów 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 informacji i opinii na podstawie Twoich postępów. Proces tworzenia będzie przebiegać w następujący sposób:

• Integracja zostanie najpierw opracowana w środowisku piaskownicy. W środowisku piaskownicy Google należy używać eksportu danych produkcyjnych (lub nawet bezpośrednio danych produkcyjnych). Dzięki temu Twój proces programowania obejmie wszystkie przypadki brzegowe, a Google będzie mogło ocenić jakość danych i lepiej Ci pomagać na podstawie Twojego modelu danych.
• Gdy zakończysz przesyłanie i będziesz codziennie przesyłać pliki danych Merchant, Services i Deals w środowisku testowym Google, zespół Google oceni Twoje pliki danych. Gdy zespół Google zatwierdzi Twój 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 Twoja integracja zostanie uruchomiona.

Monitorowanie

Aby zapewnić użytkownikom wygodę, przed wprowadzeniem ofert i po nim będziemy sprawdzać, czy są one ważne, prawidłowe i zgodne z naszymi zasadami. W tym celu Google będzie korzystać z weryfikacji manualnej i automatycznej. Wyniki tych weryfikacji będą dostępne na panelu ofert w Centrum działań (tylko w wersji produkcyjnej). 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 indeksujące)

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 sprawdzeń dziennie, oznacza to, że 5000 razy dziennie (równomiernie rozłożonych w ciągu dnia, czyli mniej więcej raz na 17 sekund) nasz robot wykonuje wszystkie te czynności, które wykonuje 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 programów do pobierania danych ze stron internetowych

Aby uniknąć zablokowania narzędzia do pobierania danych z sieci (co może spowodować, że uzna ono, że oferty są niedostępne), upewnij się, że Twój system zawsze zezwala na wysyłanie zapytań do strony przez to narzędzie. Aby zidentyfikować nasz program do pobierania danych ze stron internetowych:

• Klient użytkownika robota skanującego będzie zawierać ciąg znaków „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ą z Google, korzystając z odwrotnego wyszukiwania DNS zgodnie z zaleceniami w artykule „Weryfikowanie Googlebota i innych robotów Google”. W naszym przypadku rozpoznawanie odwrotnego DNS przebiega w ten sposób: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 buforowania HTTP.